home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Libris Britannia 4
/
science library(b).zip
/
science library(b)
/
TECHNICA
/
COMPUTER
/
H254.ZIP
/
IRITSM3S.ZIP
/
DOCS
/
IRIT.SRC
(
.txt
)
next >
Wrap
LaTeX Document
|
1992-03-10
|
134KB
|
3,019 lines
;This is the source file to create documentation for the IRIT solid modeler.
;First character in line specifies the action to take for this line/next block
;as follows:
; ';' - a comment that is always ignored.
; '#' - all lines following this line until next '#' are indented as an array.
; Four integers follows specifying indentations, # of elements per
; line, whether or not to put an internal vertical seperators, and
; if entries are row ordered (1) or col ordered (2).
; '@' - latex only manual. Latex commands can appear within this line.
; '!' - plain text and irit docs only manual - keywords/headers.
; '&' - plain text only manual - headers.
; '$' - terminator for current block.
; latex commands can appear in regular text limited to a single line as
; {\command *}. For plain text the {\command } will be filtered out.
; Escaped characters via '\' (i.e. \#) will be left escaped (\#) in the
; latex output but unescaped (#) in the plain output.
; IRIT solid modeler (C) Gershon Elber 1991.
@% Irit Solid modeler latex manual.
@% Authors: Gershon Elber
@% Date: Tri Nov 29, 1991
@% Copyright (c) 1991 Gershon Elber
@\documentstyle[11pt]{article}
@\oddsidemargin -.195in
@\evensidemargin -.195in
@\textwidth 6.50in
@\topmargin -.5in
@\textheight 9.5in
@\begin{document}
@\pagestyle{empty}
@ \rule{0in}{3in}
@ \begin{center}
@ {\huge\bf IRIT}\\
@ \vspace{3cm}
@ {\Large A Solid modeling Program}\\
@ \vspace{2cm}
@ {\large Copyright (C) 1989, 1990, 1991 Gershon Elber}\\
@ \vspace{1cm}
@ {\large EMail: gershon@gr.utah.edu }\\
@ \vfill
@ {\small This manual is for IRIT version 3.0.}
@ \end{center}
@\newpage
@\tableofcontents
@\newpage
@\setcounter{page}{1}
@\markright{{\em {\bf Irit Solid modeler}}\hfil G. Elber}
@\pagestyle{myheadings}
@\newpage
@%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@\section{Introduction}
!INTRODUCTION
{\em IRIT} is a small solid modeler developed for educational purposes. Although
small, it is now powerful enough to create quite complex scenes. I wrote
it mainly so I can learn all the little small and not so small problems
in developing such a system.
{\em IRIT} started as a polygonal solid modeler and was originally developed
(and mostly still is) on an IBM PC under MSDOS. Version 2.0 was also ported
to X11 and version 3.0 to SGI 4D systems. Version 3.0 also includes
quite a few free form curves and surfaces tools. See the UPDATE.NEW
file for more detailed update information.
@\section{Copyrights}
!COPYRIGHTS
BECAUSE {\em IRIT} AND ITS SUPPORTING TOOLS AS DOCUMENTED IN THIS DOCUMENT
ARE LICENSED FREE OF CHARGE, I PROVIDE ABSOLUTELY NO WARRANTY, TO THE EXTENT
PERMITTED BY APPLICABLE STATE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING, I
GERSHON ELBER PROVIDE {\em IRIT} PROGRAM AND ITS SUPPORTING TOOLS "AS IS" WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.
THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THESE PROGRAMS IS WITH
YOU. SHOULD THE {\em IRIT} PROGRAMS PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
NECESSARY SERVICING, REPAIR OR CORRECTION.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL GERSHON ELBER,
BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES,
OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR A
FAILURE OF THE PROGRAMS TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY GERSHON
ELBER) THE PROGRAMS, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.
@\smallskip
{\em IRIT} is a freeware solid modeler. It is not public domain since I
hold copyrights on it. However unless you are to sell or attempt to make
money from any part of this code and/or any model you made with this solid
modeler, you are free to make anything you want with it.
You are not obligated to me or to anyone else in any way by using {\em IRIT}.
You are encourage to share any model you made with it, but the models
you made with it are {\em yours}, and you have no obligation to share them.
You can use this program and/or any model created with it for any non
commerical and non profit purposes only. An acknowledgement on the way the
models were created would be nice but is {\em not} required.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{Command Line Options and Set Up}
!SETUP
The {\em IRIT} program reads a file called {\bf IRIT.CFG} each time it is executed.
This file configures the system. It is a regular text file with comments, so
you can edit it and properly modify it for your environment.
This file is being searched for in all directories as specified by the
PATH environment variable on MSDOS BC++ port or in the IRIT\_PATH environment
variable under UNIX hosts or MSDOS DJGPP port.
For example 'setenv IRIT\_PATH /u/gershon/irit/bin/'.
Note IRIT\_PATH must terminate with '/'. If the variables is not set only
the current directory is being searched for {\bf IRIT.CFG} under UNIX systems.
Since there exists a configuration file for MSDOS BC++ called IRIT-DOS.CFG,
for MSDOS DJGPP called IRIT\_DJG.CFG, and for UNIX called IRIT-UNX.CFG, make
sure you copy the right one for your system, into {\bf IRIT.CFG}.
In addition, if exists, a file by the name of {\bf IRITINIT.IRT} will be
automatically executed before any other '.irt' file. This file may contain
any {\em IRIT} command. It is the proper place to put your ALIASs if you have
some. This file will be searched much the same way {\bf IRIT.CFG} is. The
name of this initialization file may be changed by setting the StartFile
entry in the configuration file.
Under MSDOS the solid modeler can be executed in text mode (see the .cfg
and the -t flag below) on virtually any MSDOS compatible system. The BC++ port
uses Borlands BGI interface which makes it possible to use almost any device
that has a BGI interface from Hercules to a Super VGA. See the configuration
file for the supported device. The DJGPP port can be used on any system that
has graphic driver for it in this compiler.
Under BC++ the coprocessor will be used if detected but floating pointing
emulation will take place otherwise. Under DJGPP the provided emulator
(emu387) must be used if no 387 exists. If a mouse or a joystick exists
they can be use by enabling their respective flags in the configuration
file. The mouse sensitivity can be controlled via the configuration file
MouseSensitivity flag. In addition whether a mouse or a joystick exists or
not, the numeric keypad can be used to move the cursor as well. Shifted keys
will move the cursors 10 pixels at a time instead of one.
Since MSDOS does not support windowing system, an interface library called
intr\_lib is used and which provides the windowing and interfacing
capabilities expected from a windowing system. Four windows are created
under BC++, three under DJGPP:
# 19 2 0 1
View
The window where geometry is displayed.
Transformation
The window holding the transformation interaction.
This window pops up with INTERACT command, by default.
Input
The window input is keyed in/sourced from a file.
Status
Status window, mainly for core left display (only BC++).
These windows can be placed everywhere in the screen by specifing their
position and size in the configuration file. Border width and color of
the window can be specified in the configuration file as well as other
window attributes such as smooth scrolling and window headers.
Furthermore, these windows can be moved, resized, poped, or pushed during
a session via a pop up window triggered by the left mouse button (EXECUTE -
see INTERACT) or F1 keystroke. Note however that while the mouse cursor is
on the Input window scroll bar or in the Trans window, EXECUTE has a
different meaning and the pop up menu will not be displayed. The following
entries can be found in the pop up menu, and their meaning.
# 12 2 0 1
Redraw all
Redraw all windows. No window configuration is modified.
Move
Move a window. Window to move is picked by left mouse button.
Resize
Resize a window. Window to resize is picked as above.
Pop up a window. Window to pop up is picked as above.
Push
Push up a window. Window to push down is picked as above.
Zoom
Zoom a window to full screen. Window is picked as above.
Zoom on a zoomed window restore the window original size.
Reset
Reset all windows to their default position and size.
Headers
Toggle the display of windows header - names.
Under UNIX using X11 add the following options to your .Xdefaults. Most
are self explanatory. The Trans attributes control the transformation
window, while View control the view window. SubWin attributes control
the subwindows within the Transformation window.
# 33 2 0 1
irit*Trans*BackGround:
NavyBlue
irit*Trans*BorderColor:
Red
irit*Trans*BorderWidth:
irit*Trans*TextColor:
Yellow
irit*Trans*SubWin*BackGround:
DarkGreen
irit*Trans*SubWin*BorderColor:
Magenta
irit*Trans*Geometry:
=150x500+500+0
irit*Trans*CursorColor:
Green
irit*View*BackGround:
NavyBlue
irit*View*BorderColor:
Red
irit*View*BorderWidth:
irit*View*Geometry:
=500x500+0+0
irit*View*CursorColor:
Red
If poly3d is used under SGI gl library, you can set the prefered windows
location in the poly3d.cfg. No color control is provided at this time.
A session can be logged into a file as set via LogFile in the configuration
file. See also the LOGFILE command.
When developing new model under MSDOS, it is extremely convenient to switch
between the solid modeler and an editor of your choice to edit the '.irt' file.
The solid modeler provides a way to fork to an editor of your choice to edit
the current '.irt' program you develop. Set EditPrgm (in irit.cfg) to the
editor of your choice, which should be small for fast access. Specify the
full path to that editor. Use the edit command in {\em IRIT} to call it. Only one
argument is given to the editor once forking to it - the '.irt' file name as
given to the edit command (see EDIT command). You can alias the command to
make it even faster as it is done in the current iritinit.irt - {\em IRIT}
initialization file.
Under UNIX one can use the gnu emacs irit.el {\em IRIT} mode provided in this
package to run {\em IRIT}.
The following command line options are available:
@\begin{verbatim}
IRIT [-t] [-z] [file.irt]
@\end{verbatim}
# 10 2 1 1
Puts {\em IRIT} into text mode. No graphics will be displayed and
the INTERACT and VIEW commands will be ignored. Useful when
one needs to execute an irt file to create data on a tty device...
Prints usage message and current configuration/version
information.
file.irt
A file to directly invoke instead of waiting to input from
stdin.
@\section{First Usage}
!FIRSTUSAGE
Once executed, the program opens four windows under MSDOS BC++ (three
under MSDOS DJGPP - no status window): view, status, trans and input windows,
and opens a view window under UNIX.
Commands are entered through the input window, which is in the same window
as the shell executed {\em IRIT} under UNIX. Objects are viewed in the view
window, and the status window is used as an auxiliary window (MSDOS only).
Some important commands to begin with are
1. include("file.irt"); - will execute the commands in file.irt. Note
include can be recursive up to 10 levels. To execute the demo
(demo.irt) simply type 'include("demo.irt");'. Another way to run
the demo is by typing DEMO (must be capitalized as this is an alias
loaded via the iritinit.irt initialization file - see the ALIAS
command for more).
2. help(""); - will print all available commands and how to get help on
them. A file by the name irit.hlp will be searched as irit.cfg is
being searched (see above), to provide the help.
3. exit(); - close everything and exit {\em IRIT}.
Be careful. Most operators are overloaded. This means that you can multiply
two scalars (numbers) or two vectors or even two matrices with the same
multiplication symbol ($*$). To get its on line type 'help("$*$");'
The best way to learn this program (like any other program...) is by
playing with it. Print the manual and study each of the commands available.
Study the demo programs ($*$.irt) provided as well.
Under MSDOS, input from keyboard has full line editing capability:
1. Up/Down arrow : retrieve old command for 10 last commands.
2. Left/Right arrows : to move left and right along the line.
3. Home/End : to move to beginning/end of line.
4. Delete : to delete the character the cursor is on.
5. Back space : to delete one char backward.
6. Insert : toggles insert/overwrite mode. Note cursor shape is modified.
7. Esc : clear the entire line.
8. CR : to accept line and quit.
@\section{Data Types}
!DATATYPES
These are the Data Types recognized the system. They are also used to
define the calling sequences of the different functions below:
# 18 2 1 1
{\bf ConstantType}
Scalar real type that cannot be modified.
{\bf NumericType}
Scalar real type.
{\bf VectorType}
3D real type vector (points/vectors).
{\bf CtlPtType}
Curve or Surface Control Point.
{\bf MatrixType}
4 by 4 matrix (homogeneous transformation matrix).
{\bf PolygonType}
Object consists of Polygons.
{\bf PolylineType}
Object consists of Polylines.
{\bf CurveType}
Object consists of Curves.
{\bf SurfaceType}
Object consists of Surfaces.
{\bf GeometriceType}
One of Polygon/lineType, CurveType, SurfaceType.
{\bf GeometricTreeType}
A list of GeometricTypes or GeometricTreeTypes.
{\bf StringType}
Sequence of chars within double quotes - "A string".
Current implementation is limited to 80 chars.
{\bf AnyType}
Any of the above.
{\bf ListType}
List of (any of the above type) objects. Implementation
is currently limited to 250 (50 MSDOS) objects in a list.
@\section{Commands summary}
!COMMANDS
These are all the commands and operators supported by the {\em IRIT} solid modeler:
# 11 6 1 0
\verb+^+
ACOS
ALIAS
AREA
ASIN
ATAN
ATAN2
ATTRIB
BEEP
BOOLSUM
CBEZIER
CBSPLINE
CDIVIDE
CEDITPT
CEVAL
CHDIR
CIRCLE
CIRCPOLY
CLOSED
CMESH
COLOR
COMMENT
CON2
CONE
CONVEX
CPOLY
CRAISE
CREFINE
CREGION
CROSSEC
CSURFACE
CTANGENT
CTLPT
CYLIN
EDIT
EXIT
EXTRUDE
FREE
GBOX
GPOLYGON
GPOLYLINE
HELP
INCLUDE
INTERACT
LIST
LOAD
LOGFILE
MERGEPOLY
NORMAL
OFFSET
PAUSE
POLY
ROTX
ROTY
ROTZ
RULEDSRF
SAVE
SBEZIER
SBSPLINE
SCALE
SDIVIDE
SEDITPT
SEVAL
SFROMCRVS
SNOC
SNORMAL
SPHERE
SQRT
SRAISE
SREFINE
SREGION
STANGENT
SURFREV
SWEEPSRF
SYSTEM
TIME
TORUS
TRANS
VARLIST
VECTOR
VIEW
VOLUME
@\section{Functions and Variables}
!FUNCTIONS
@ This sections lists all the functions supported by the {\em IRIT} system
@ according to their classes - the object type they return.
These are the functions returning a {\bf NumericType}:
# 11 5 1 0
ACOS
AREA
ASIN
ATAN
ATAN2
CPOLY
SQRT
VOLUME
These are the functions returning a {\bf GeometricType}:
# 11 6 1 0
BOOLSUM
CBEZIER
CBSPLINE
CDIVIDE
CEDITPT
CEVAL
CIRCLE
CIRCPOLY
CMESH
CON2
CONE
CONVEX
CPOLY
CRAISE
CREFINE
CREGION
CROSSEC
CSURFACE
CTANGENT
CTLPT
CYLIN
EXTRUDE
GBOX
GPOLYGON
GPOLYLINE
MERGEPOLY
OFFSET
POLY
RULEDSRF
SBEZIER
SBSPLINE
SDIVIDE
SEDITPT
SEVAL
SFROMCRVS
SNORMAL
SPHERE
SRAISE
SREFINE
SREGION
STANGENT
SURFREV
SWEEPSRF
TORUS
These are the functions to linearly transform an object:
# 11 5 1 0
ROTX
ROTY
ROTZ
SCALE
TRANS
These are the miscellaneous functions:
# 11 6 1 0
ALIAS
ATTRIB
BEEP
CHDIR
CLOSED
COLOR
COMMENT
EDIT
EXIT
FREE
HELP
INCLUDE
INTERACT
LIST
LOAD
LOGFILE
NORMAL
PAUSE
SAVE
SNOC
SYSTEM
TIME
VARLIST
VECTOR
VIEW
These are the variables predefined in the system:
# 11 5 1 0
AXES
DRAWCTLPT
DUMPLVL
ECHOSRC
FLAT4PLY
INTERCRV
INTERNAL
MACHINE
RESOLUTION
VIEW\_MAT
These are the constants predefined in the system:
# 11 6 1 0
APOLLO
BLACK
BLUE
CYAN
FALSE
GREEN
KV\_FLOAT
KV\_OPEN
MAGENTA
MSDOS
TRUE
UNIX
WHITE
YELLOW
@\section{Language description}
!LANGUAGE
The front end of the {\em IRIT} solid modeler is an infix parser that mimics
some of the C language behavior. The infix operators that are supported
are plus (+), minus (-), multiply (*), divide (/), and power (\verb+^+) for
numeric operators and with the same precedence as in C.
However, unlike the C language, these operators are overloaded,
@\footnote{In fact the C language do support overloaded operators to some
@extent: '1 + 2' and '1.0 + 2.0' implies invocation of two different
@actions.}
or different action is taken based upon the different operands.
This means that one can write '1 + 2' in which the plus sign is a regular
numetic addition, or one can write 'PolyObj1 + PolyObj2' in which the plus
sign is now the Boolean operation of union between two geometric objects.
The exact way each operator is overloaded is defined below.
In this environment the representation of reals, integers, and even
Boolean data is identical. Data is automatically promoted as necessary.
The constants TRUE and FALSE are defined as 1.0 and 0.0 respectively,
for example.
Each expression is terminated by a semicolon. An expression can be as
simple as 'a;' which prints the value of variable a, or as complex as:
@\begin{verbatim}
for ( (t = 1.1), 0.1, 1.9,
(
( cb1 = csurface( sb, COL, t ) ):
color( cb1, green ):
snoc( cb1, cb_all )
)
);
@\end{verbatim}
Once a complete expression is read in and parsed correctly (i.e. no syntax
errors were found), it is executed. Before each operator or a function
are executed, parameter type matching tests are being made to make sure
the operator can be applied to these operand(s), or the function gets the
correct set of arguments.
The parser is almost totally case insensitive (with one exception - see
the ALIAS command) so Obj, obj and OBJ will refer to the same object while
MergePoly, MERGEPOLY, and margePoly will refer to the same function.
Objects (Variables if you prefer) need not be declared. Simply use them
when you need them. Object names may be any alpha-numeric (and underscore)
string of at most 10 characters. By assigning to an old object, the old
object will be automatically deleted and if necessary its type will be
changing on the fly. For example:
@\begin{verbatim}
V = sin( 45 * pi / 180.0 );
V = V * vector( 1, 2, 3 );
V = V * rotx( 90 );
V = V * V;
@\end{verbatim}
will assign to V a NumericType of sine of 45 degrees, the VectorType
( 1, 2, 3 ) scaled by the sine of 45, rotate that vector around the X axis
by 90 degrees, and finally a NumericType which is its dot product.
The parser will read from stdin unless a file was specified on the command
line or an INCLUDE command was executed. In both cases, when done reading
from the file, the parser will again wait for input from stdin. In order
to execute a file and quit when the file is done, put an EXIT command as
the last command in the file.
@\section{Operator overloading}
@ This section lists the way the basic operators $+$, $-$, $*$, $/$, and
@ \verb+^+ are overloaded. In other words, what action is taken by each
@ of these operators depending upon its arguments.
@\subsection{Overloading $+$}
The $+$ operator is overloaded above the following domains:
@\begin{verbatim}
NumericType + NumericType -> NumericType
VectorType + VectorType -> VectorType
MatrixType + MatrixType -> MatrixType
PolygonType + PolygonType -> PolygonType (Boolean UNION operation)
CurveType + CurveType -> CurveType (Curve curve chaining)
CurveType + CtlPtType -> CurveType (Curve control point chaining)
CtlPtType + CtlPtType -> CurveType (Control points chaining)
ListType + ListType -> ListType (Append lists operator)
@\end{verbatim}
Note: Boolean UNION of two disjoint objects (no common volume) will result
with the two objects combined. It is the USER responsibility to make sure that
the non intersecting object are also disjoint - this system only tests for
no intersection.
@\subsection{Overloading $-$}
The $-$ operator is overloaded above the following domains:
As a Diadic operator:
@\begin{verbatim}
NumericType - NumericType -> NumericType
VectorType - VectorType -> VectorType
MatrixType - MatrixType -> MatrixType
PolygonType - PolygonType -> PolygonType (Boolean SUBTRACT operation)
@\end{verbatim}
As a Monadic operator:
@\begin{verbatim}
- NumericType -> NumericType
- VectorType -> VectorType (Scaling all vector by -1)
- MatrixType -> MatrixType (Scaling all matrix by -1)
- PolygonType -> PolygonType (Boolean NEGATION operation)
- CurveType -> CurveType (Curve parameterization is reversed)
- SurfaceType -> SurfaceType (Surface parameterization is reversed)
@\end{verbatim}
Note: Boolean SUBTRACT of two disjoint objects (no common volume) will result
with an empty object. For both a curve and a surface parameterization reverse
opeartion (Monadic minus) causes the object normal to be flipped as a side
effect.
@\subsection{Overloading $*$}
The $*$ operator is overloaded above the following domains:
@\begin{verbatim}
NumericType * NumericType -> NumericType
VectorType * NumericType -> VectorType (Vector scaling)
VectorType * VectorType -> NumericType (Inner product)
MatrixType * NumericType -> MatrixType (Matrix Scaling)
MatrixType * VectorType -> VectorType (Vector transform)
MatrixType * MatrixType -> MatrixType (Matrix multiplication)
MatrixType * GeometricType -> GeometricType (Object transform)
MatrixType * ListType -> ListType (Object hierarchy transform)
PolygonType * PolygonType -> PolygonType (Boolean INTERSECTION operation)
@\end{verbatim}
Note: Boolean INTERSECTION of two disjoint objects (no common volume) will
result with an empty object. Object hierarchy transform transforms any
transformable object (GeometricType) found in the list recursively.
@\subsection{Overloading $/$}
The $/$ operator is overloaded above the following domains:
@\begin{verbatim}
NumericType / NumericType -> NumericType
PolygonType / PolygonType -> PolygonType (Boolean CUT operation)
@\end{verbatim}
Note: Boolean CUT of two disjoint objects (no common volume) will result
with an empty object.
@\subsection{Overloading \^{\ }}
The \verb+^+ operator is overloaded above the following domains:
@\begin{verbatim}
NumericType ^ NumericType -> NumericType
MatrixType ^ NumericType -> MatrixType (Matrix to the power)
PolygonType ^ PolygonType -> PolygonType (Boolean MERGE operation)
@\end{verbatim}
Note: Boolean MERGE simply merges the two sets of polygons without any
intersection tests. Matrix powers must be positive integers or -1 in which
the matrix inverse (if exists) is computed.
@\subsection{Assignments}
Assignments are allowed as side effects, any place in any expressions:
If Expr is an expression, then (var = Expr) is the exact same expression
with the side effect of setting Var to that value. There is no guarantee
on the order of evaluation, so using Vars that are set within same
expression are a bad practice.
Any assignment which is not at top level, MUST be within parenthesis.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{Function's Description}
&Function's Description
@ The function description below defines their calling sequence in ANSI C
@ notation. Listed are all the functions the system knows about in alphabetic
@ order, according to their classes.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{NumericType returning functions}
&NumericType returning functions
@\subsubsection{ABS}
@\begin{verbatim}
NumericType ABS( NumericType Operand )
@\end{verbatim}
Returns the absolute value of the given {\bf Operand}.
@\subsubsection{ACOS}
!ACOS
@\begin{verbatim}
NumericType ACOS( NumericType Operand )
@\end{verbatim}
Returns the arc cosine value (in radians) of the given {\bf Operand}.
@\subsubsection{AREA}
!AREA
@\begin{verbatim}
NumericType AREA( PolygonType Object )
@\end{verbatim}
Return the area of the given {\bf Object} (in object units). Returned is
the real area of the polygonal object - not the primitive it might approximate.
That means that the area of a polygonal approximation to a sphere will be
returned, not the sphere area.
@\subsubsection{ASIN}
!ASIN
@\begin{verbatim}
NumericType ASIN( NumericType Operand )
@\end{verbatim}
Returns the arc sine value (in radians) of the given {\bf Operand}.
@\subsubsection{ATAN}
!ATAN
@\begin{verbatim}
NumericType ATAN( NumericType Operand )
@\end{verbatim}
Returns the arc tangent value (in radians) of the given {\bf Operand}.
@\subsubsection{ATAN2}
!ATAN2
@\begin{verbatim}
NumericType ATAN2( NumericType Operand1, NumericType Operand2 )
@\end{verbatim}
Returns the arc tangent value (in radians) of the given ratio:
{\bf Operand1} / {\bf Operand2}, over the whole angle circle.
@\subsubsection{COS}
@\begin{verbatim}
NumericType COS( NumericType Operand )
@\end{verbatim}
Returns the cosine value of the given {\bf Operand} (in radians).
@\subsubsection{CPOLY}
!CPOLY
@\begin{verbatim}
NumericType CPOLY( PolygonType Object )
@\end{verbatim}
Returns the number of polygons in the given polygonal {\bf Object}.
@\subsubsection{EXP}
@\begin{verbatim}
NumericType EXP( NumericType Operand )
@\end{verbatim}
Returns the natural exponent value of the given {\bf Operand}.
@\subsubsection{LN}
@\begin{verbatim}
NumericType LN( NumericType Operand )
@\end{verbatim}
Returns the natural logarithm value of the given {\bf Operand}.
@\subsubsection{LOG}
@\begin{verbatim}
NumericType LOG( NumericType Operand )
@\end{verbatim}
Returns the base 10 logarithm value of the given {\bf Operand}.
@\subsubsection{SIN}
@\begin{verbatim}
NumericType SIN( NumericType Operand )
@\end{verbatim}
Returns the sine value of the given {\bf Operand} (in radians).
@\subsubsection{SQRT}
!SQRT
@\begin{verbatim}
NumericType SQRT( NumericType Operand )
@\end{verbatim}
Returns the square root value of the given {\bf Operand}.
@\subsubsection{TAN}
@\begin{verbatim}
NumericType TAN( NumericType Operand )
@\end{verbatim}
Returns the tangent value of the given {\bf Operand} (in radians).
@\subsubsection{VOLUME}
!VOLUME
@\begin{verbatim}
NumericType VOLUME( PolygonType Object )
@\end{verbatim}
Return the volume of the given {\bf Object} (in object units). Returned is
the real volume of the polygonal object - not the object it might approximate.
This routine decompose all non convex polygons to convex ones as side
effect (see CONVEX).
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{GeometricType returning functions}
&GeometricType returning functions
@\subsubsection{ARC}
@\begin{verbatim}
CurveType ARC( VectorType StartPos, VectorType Center, VectorType EndPos )
@\end{verbatim}
An arc constructor between two end points {\bf StartPos} and {\bf EndPos}
centered at {\bf Center}. Arc will always be less than 180 degrees so the
shortest arc path from {\bf StartPos} to {\bf EndPos} is selected. The
case where {\bf StartPos}, {\bf Center}, and {\bf EndPos} are colinear is
illegal, since it attempts to define a 180 degrees arc. Arc is constructed
as a single rational quadratic Bezier curve. Example:
@\begin{verbatim}
Arc1 = ARC( vector( 1.0, 0.0, 0.0 ),
vector( 1.0, 1.0, 0.0 ),
vector( 0.0, 1.0, 0.0 ) );
@\end{verbatim}
constructs a 90 degrees arc tangent to both X and Y axes at coordinate 1.
@\subsubsection{BOOLSUM}
!BOOLSUM
@\begin{verbatim}
SurfaceType BOOLSUM( CurveType Crv1, CurveType Crv2,
CurveType Crv3, CurveType Crv4 )
@\end{verbatim}
Construct a surface using the provided four curves as its four boundary
curves. Curves do not have to have the same order or type and will be
promoted to their least common denominator. The four curves end points
should match as follows:
# 30 2 0 1
{\bf Crv1} start point,
to {\bf Crv3} start point.
{\bf Crv1} end point,
to {\bf Crv4} start point.
{\bf Crv2} start point,
to {\bf Crv3} end point.
{\bf Crv2} end point,
to {\bf Crv4} end point.
where {\bf Crv1} and {\bf Crv2} are the two boundaries in one parameteric
direction and {\bf Crv3} and {\bf Crv4} are the two in the other.
Example:
@\begin{verbatim}
Cbzr1 = cbezier( list( ctlpt( E3, 0.1, 0.1, 0.1 ),
ctlpt( E3, 0.0, 0.5, 1.0 ),
ctlpt( E3, 0.4, 1.0, 0.4 ) ) );
Cbzr2 = cbezier( list( ctlpt( E3, 1.0, 0.2, 0.2 ),
ctlpt( E3, 1.0, 0.5, -1.0 ),
ctlpt( E3, 1.0, 1.0, 0.3 ) ) );
Cbsp3 = cbspline( 4,
list( ctlpt( E3, 0.1, 0.1, 0.1 ),
ctlpt( E3, 0.25, 0.0, -1.0 ),
ctlpt( E3, 0.5, 0.0, 2.0 ),
ctlpt( E3, 0.75, 0.0, -1.0 ),
ctlpt( E3, 1.0, 0.2, 0.2 ) ),
list( KV_OPEN ) );
Cbsp4 = cbspline( 4,
list( ctlpt( E3, 0.4, 1.0, 0.4 ),
ctlpt( E3, 0.25, 1.0, 1.0 ),
ctlpt( E3, 0.5, 1.0, -2.0 ),
ctlpt( E3, 0.75, 1.0, 1.0 ),
ctlpt( E3, 1.0, 1.0, 0.3 ) ),
list( KV_OPEN ) );
Srf = BOOLSUM( Cbzr1, Cbzr2, Cbsp3, Cbsp4 );
@\end{verbatim}
@\subsubsection{BOX}
@\begin{verbatim}
PolygonType BOX( VectorType Point,
NumericType Dx, NumericType Dy, NumericType Dz )
@\end{verbatim}
Creates a main planes parallel BOX polygonal object, defined by {\bf Point} as
base position, and {\bf Dx, Dy, Dz} as BOX dimensions. Note negative dimensions
are allowed. Example:
@\begin{verbatim}
B = BOX( vector( 0, 0, 0 ), 1, 1, 1);
@\end{verbatim}
creates a unit cube from 0 to 1 in all axes.
@\subsubsection{CBEZIER}
!CBEZIER
@\begin{verbatim}
CurveType CBEZIER( ListType CtlPtList )
@\end{verbatim}
Creates a Bezier curve out of the provided control point list. {\bf CtlPtList}
is a list of control points, all of the same type (E2, E3, P2, or P3).
Example:
@\begin{verbatim}
s45 = sin(pi / 4);
Arc90 = CBEZIER( list( ctlpt( P2, 1.0, 0.0, 1.0 ),
ctlpt( P2, s45, s45, s45 ),
ctlpt( P2, 1.0, 1.0, 0.0 ) ) );
@\end{verbatim}
constructs an arc of 90 degrees as a rational quadratic Bezier curve.
@\subsubsection{CBSPLINE}
!CBSPLINE
@\begin{verbatim}
CurveType CBSPLINE( NumericType Order, ListType CtlPtList,
ListType KnotVector )
@\end{verbatim}
Creates a Bspline curve out of the provided control point list and the
knot vector, with the specified order. {\bf CtlPtList} is a list of control points,
all of the same type (E2, E3, P2, or P3) defining the curve control polygon.
The length of the {\bf KnotVector} must be equal to the number of control
points in {\bf CtlPtList} plus {\bf Order}.
Example:
@\begin{verbatim}
s45 = sin(pi / 4);
HalfCirc = CBSPLINE( 3,
list( ctlpt( P3, 1.0, 0.0, 0.0, 1.0 ),
ctlpt( P3, s45, -s45, 0.0, s45 ),
ctlpt( P3, 1.0, -1.0, 0.0, 0.0 ),
ctlpt( P3, s45, -s45, 0.0, -s45 ),
ctlpt( P3, 1.0, 0.0, 0.0, -1.0 ) ),
list( 0, 0, 0, 1, 1, 2, 2, 2 ) );
@\end{verbatim}
constructs an arc of 180 degrees in the XZ plane as a rational quadratic
Bspline curve.
The knot vector list may be specified as {\bf list( KV\_OPEN )} or as
{\bf list( KV\_FLOAT )} in which a uniform open or floating knot vector
with the appropriate length is automatically constructed.
@\subsubsection{CDIVIDE}
!CDIVIDE
@\begin{verbatim}
ListType CDIVIDE( CurveType Curve, NumericType Param )
@\end{verbatim}
Subdivides a curve into two at the specified parameter value. {\bf Curve}
can be either a Bspline curve in which {\bf Param} must be within Curve
parametric domain or a Bezier curve in which {\bf Param} must be in the
0 to 1 range.
Returned is a list of the two sub-curves. The individual curves may be
extracted from the list using the NTH command. For example:
@\begin{verbatim}
CrvLst = CDIVIDE( Crv, 0.5 );
Crv1 = nth( CrvLst, 1 );
Crv2 = nth( CrvLst, 2 );
@\end{verbatim}
subdivides the curve {\bf Crv} at the parameter value 0.5.
@\subsubsection{CEDITPT}
!CEDITPT
@\begin{verbatim}
CurveType CEDITPT( CurveType Curve, CtlPtType CtlPt, NumericType Index )
@\end{verbatim}
Provides a simple mechanism to manually modify a single control point number
{\bf Index} (base count is 0) in {\bf Curve}, by substituting {\bf CtlPt}
instead. {\bf CtlPt} must have the same point type as {\bf Curve} points.
Original curve {\bf Curve} is not modified. Example:
@\begin{verbatim}
CPt = ctlpt( E3, 1, 2, 3 );
NewCrv = CEDITPT( Curve, CPt, 1 );
@\end{verbatim}
constructs a {\bf NewCrv} with the second control point of {\bf Curve} being
{\bf CPt}.
@\subsubsection{CEVAL}
!CEVAL
@\begin{verbatim}
CtlPtType CEVAL( CurveType Curve, NumericType Param )
@\end{verbatim}
Evaluates the provided {\bf Curve} at the given {\bf Param } value.
{\bf Param} should be with the curve domain if {\bf Curve} is a Bspline
curve, or between 0 and 1 if {\bf Curve} is a Bezier curve. Returned
control point has the same type as the {\bf Curve} control points. Example:
@\begin{verbatim}
CPt = CEVAL( Crv, 0.25 );
@\end{verbatim}
evaluates {\bf Crv} at the parameter value of 0.25.
@\subsubsection{CIRCLE}
!CIRCLE
@\begin{verbatim}
CurveType CIRCLE( VectorType Center, NumericType Radius )
@\end{verbatim}
Construct a circle at the specified {\bf Center} with the specified
{\bf Radius}. Returned circle is a Bspline curve of four piecewise Bezier
90 degree arcs. Circle is always parallel to the XY plane. Use the linear
transformation routines to place the circle in the appropriate location.
@\subsubsection{CIRCPOLY}
!CIRCPOLY
@\begin{verbatim}
PolygonType CIRCPOLY( VectorType Normal, VectorType Trans, NumericType Radius )
@\end{verbatim}
As in this solid modeler, open objects are allowed (although any two
objects intersection should form a closed loop), a plane (open!) object
also exists. The function defines a circular polygon with the given
{\bf Normal}, and includes the {\bf Trans} point. It is implemented as a FINITE
circle with resolution (see RESOLUTION) edges, radius {\bf Radius} and center
{\bf Trans} on that plane. It is the user responsibility to make sure that any
Boolean operation on it (or any other open object) will create closed loops as
intersecting curves and/or open loops terminated on its boundary (no
termination in the middle of it is allowed).
Alternative to the function are manual construction of the required plane
as a single polygon using POLY, or construction of a flat ruled surface using
RULEDSRF.
@\subsubsection{CMESH}
!CMESH
@\begin{verbatim}
CurveType CMESH( SurfaceType Srf, ConstantType Direction, NumericType Index )
@\end{verbatim}
Returns a single ROW or COLumn as specified by the {\bf Direction} and
{\bf Index} (base count is 0) of the surface {\bf Srf} control mesh.
Returned curve will have the same knot vector as {\bf Srf} in the
appropriate direction. See also CSURFACE.
Note this curve is {\em not} necessarily in the surface {\bf Srf}. Example:
@\begin{verbatim}
Crv = CMESH( Srf, COL, 0 );
@\end{verbatim}
extracts the first column of surface {\bf Srf} as a curve.
@\subsubsection{CON2}
!CON2
@\begin{verbatim}
PolygonType CON2( VectorType Center, VectorType Direction,
NumericType Radius1, NumericType Radius2 )
@\end{verbatim}
Create a truncated CONE geometric object, defined by {\bf Center} as CONE main
base center, CONE axes {\bf Direction}, and CONE base radii {\bf Radius1/2}.
Note {\bf Direction} magnitude also sets the CONE height. {\bf Direction} can be any
3D vector.
Unlike the regular cone (CONE) constructor which has discontinuities in
its apex generated normals, CON2 may be used to form a truncated cone but
with continuous normals.
See RESOLUTION for accuracy of CON2 approximation as polygonal model.
Example:
@\begin{verbatim}
Crv = CON2( vector( 0, 0, -1 ), vector( 0, 0, 4 ), 2, 1 );
@\end{verbatim}
constructs a truncated cone based at the XY parallel plane Z = -1, top at
plane Z = 3, and with radii of 2 and 1 respectively.
@\subsubsection{CONE}
!CONE
@\begin{verbatim}
PolygonType CONE( VectorType Center, VectorType Direction,
NumericType Radius )
@\end{verbatim}
Create a CONE geometric object, defined by {\bf Center} as CONE base center,
CONE axes {\bf Direction}, and CONE base radius {\bf Radius}. Note {\bf Direction} magnitude
also sets the CONE height. {\bf Direction} can be any 3D vector.
See RESOLUTION for accuracy of CONE approximation as polygonal model.
Example:
@\begin{verbatim}
Crv = CONE( vector( 0, 0, 0 ), vector( 1, 1, 1 ), 1 );
@\end{verbatim}
constructs a cone based in the XY parallel plane, centered at the origin
with radius 1 and with tilted apex at ( 1, 1, 1 ).
See also CON2.
@\subsubsection{CONVEX}
!CONVEX
@\begin{verbatim}
PolygonType CONVEX( PolygonType Object )
@\end{verbatim}
Coerce non convex polygons in {\bf Object}, into convex one. New vertices
are introduced into the polygonal data during this process. The Boolean
operations require the input to have convex polygons only (although it may
return non convex polygons...) and automatically coerced non convex input
polygons to convex ones, using this same routine.
However some external tools (like irit2ray, poly3d-r and poly3d-h) requires
convex polygons. This function may be used on the objects to provide that,
just before they are being saved into data files. Example:
@\begin{verbatim}
CnvxObj = CONVEX( Obj );
save("data", CnvxObj);
@\end{verbatim}
decompose non convex polygons into convex ones so that data file could be
used by external tools requiring convex polygons.
@\subsubsection{CPOLY}
!CPOLY
@\begin{verbatim}
NumericType CPOLY( PolygonType Polys )
@\end{verbatim}
Returns number of polygons in provided object. Example:
@\begin{verbatim}
DumpLvl = 1
NumPolys = CPOLY( Obj );
NumPolys;
@\end{verbatim}
prints the number of polygons in object {\bf Obj}.
@\subsubsection{CRAISE}
!CRAISE
@\begin{verbatim}
CurveType CRAISE( CurveType Curve, NumericType NewOrder )
@\end{verbatim}
Raise {\bf Curve} to the {\bf NewOrder} Order specified. Currently
implemented for Bezier curves of any order and linear Bspline curve only.
Example:
@\begin{verbatim}
Crv = ctlpt( E3, 0.0, 0.0, 0.0 ) +
ctlpt( E3, 0.0, 0.0, 1.0 ) +
ctlpt( E3, 1.0, 0.0, 1.0 );
Crv2 = CRAISE( Crv, 4 );
@\end{verbatim}
raises the 90 degrees corner linear Bspline curve {\bf Crv} to be a cubic.
@\subsubsection{CREFINE}
!CREFINE
@\begin{verbatim}
CurveType CREFINE( CurveType Curve, NumericType Replace, ListType KnotList )
@\end{verbatim}
Provides the ability to {\bf Replace} a knot vector of {\bf Curve} or refine
it. {\bf KnotList} is a list of knots to refine {\bf Curve} at and all
should be within {\bf Curve} parametric domain. If knot vector is to be
replaced, the length of {\bf KnotList} should be identical to the length
of {\bf Curve} knot vector. If {\bf Curve} is a Bezier curve, it is
automatically promoted to be a Bspline curve. Example:
@\begin{verbatim}
Crv2 = CREFINE( Crv, FALSE, list( 0.25, 0.5, 0.75 ) );
@\end{verbatim}
refines {\bf Crv} at the three knots 0.25, 0.5, and 0.75.
@\subsubsection{CREGION}
!CREGION
@\begin{verbatim}
CurveType CREGION( CurveType Curve, NumericType MinParam,
NumericType MaxParam )
@\end{verbatim}
Extracts a subdomain of {\bf Curve} between {\bf MinParam} and {\bf MaxParam}.
Both {\bf MinParam} and {\bf MaxParam} should be within {\bf Curve}
parametric domain. Example:
@\begin{verbatim}
SubCrv = CREGION( Crv, 0.3, 0.6 );
@\end{verbatim}
extracts the subdomain of {\bf Crv} from the parameter value 0.3 to the
parameter value 0.6.
@\subsubsection{CROSSEC}
!CROSSEC
@\begin{verbatim}
PolygonType CROSSEC( PolygonType Object )
@\end{verbatim}
; Invoke interactive mode to edit/create a polygon in the plane Z = 0. The
; polygon must be in the domain [0..1] in X,Y. The first polygon of the given
; Object is copied to begin with. If the given {\bf Operand} is NOT a geometric
; object, but false (numeric 0.0), a new polygon is created. Returns an (open)
; object with this one polygon only and inside side of +Z. Note that if the
; given polygon (first polygon of Object) is not on XY plane it is transformed
; to it before editing, and transformed back after.
Unfortunately, this feature is NOT implemented...
@\subsubsection{CSURFACE}
!CSURFACE
@\begin{verbatim}
CurveType CSURFACE( SurfaceType Srf, ConstantType Direction,
NumericType Param )
@\end{verbatim}
Extract an iso parametric curve out of {\bf Srf} in the specified
{\bf Direction} (ROW or COL) at the specified parameter value {\bf Param}.
{\bf Param} must be in {\bf Srf} parameter range in {\bf Direction} direction.
The returned curve is {\em in} {\bf Srf}. See also CMESH. Example:
@\begin{verbatim}
Crv = CSURFACE( Srf, COL, 0.15 );
@\end{verbatim}
extract an iso parametric curve in the COLumn direction at parameter value
0.15 from surface {\bf Srf}.
@\subsubsection{CTANGENT}
!CTANGENT
@\begin{verbatim}
VectorType CTANGENT( CurveType Curve, NumericType Param )
@\end{verbatim}
Computes the tangent vector to {\bf Curve} at the parameter value {\bf Param}.
Example:
@\begin{verbatim}
Tang = CTANGENT( Crv, 0.5 );
@\end{verbatim}
computes the tangent to {\bf Crv} at the parameter value 0.5.
@\subsubsection{CTLPT}
!CTLPT
@\begin{verbatim}
CPt = CTLPT( ConstantType E2, NumericType X, NumericType Y )
CPt = CTLPT( ConstantType E3, NumericType X, NumericType Y, NumericType Z )
CPt = CTLPT( ConstantType P2, NumericType W, NumericType X, NumericType Y )
CPt = CTLPT( ConstantType P3, NumericType W,
NumericType X, NumericType Y, NumericType Z )
@\end{verbatim}
Construct a single control point to be used in curves and surfaces
construction. Four types of points may be constructed as follows:
# 10 2 1 1
A two dimensional point with X and Y.
A three dimensional point with X, Y, and Z.
A two dimensional rational point at X/W, and Y/W.
A three dimensional rational point at X/W, Y/W, and Z/W.
Example:
@\begin{verbatim}
CPt = CTLPT( E3, 0.0, 0.0, 0.0 );
@\end{verbatim}
constructs an {\bf E3} points at the origin.
@\subsubsection{CYLIN}
!CYLIN
@\begin{verbatim}
PolylineType CYLIN( VectorType Center, VectorType Direction,
NumericType Radius )
@\end{verbatim}
Create a CYLINder geometric object, defined by {\bf Center} as CYLIN base center,
CYLIN axes {\bf Direction}, and CYLIN base radius {\bf Radius}. Note Direction magnitude
also sets the CYLIN height. {\bf Direction} can be any 3D vector.
See RESOLUTION for accuracy of CYLIN approximation as polygonal model.
Example:
@\begin{verbatim}
Crv = CYLIN( vector( 0, 0, 0 ), vector( 1, 0, 0 ), 10 );
@\end{verbatim}
constructs a cylinder along the X axis from the origin to X = 10.
@\subsubsection{EXTRUDE}
!EXTRUDE
@\begin{verbatim}
PolygonType EXTRUDE( PolygonType Object, VectorType Dir )
SurfaceType EXTRUDE( CurveType Object, VectorType Dir )
@\end{verbatim}
Creates an extrusion of the given {\bf Object}. If {\bf Object} is a
PolygonObject, its first polygon is used as the base for the extrusion in
{\bf Dir} direction, and a closed PolygonObject is constrcted. If {\bf Object}
is a CurveType, an extrusion surface is constructed instead which is {\em not}
a closed object (the two bases of the extrusion are excluded and the curve may
be open by itself).
No limitation exists on the polygon (can be non-convex), but {\bf Dir}
cannot be coplanar with the polygon plane. The curve need not be planar.
Example:
@\begin{verbatim}
Cross = cbspline( 3,
list( ctlpt( E2, -0.018, 0.001 ),
ctlpt( E2, 0.018, 0.001 ),
ctlpt( E2, 0.019, 0.002 ),
ctlpt( E2, 0.018, 0.004 ),
ctlpt( E2, -0.018, 0.004 ),
ctlpt( E2, -0.019, 0.001 ) ),
list( KV_OPEN ) );
Cross = Cross + -Cross * scale( vector( 1, -1, 1 ) );
Napkin = EXTRUDE( Cross * scale( vector( 1.6, 1.6, 1.6 ) ),
vector( 0.02, 0.03, 0.2 ) );
@\end{verbatim}
constructs a closed cross section {\bf Cross} by duplicating a half of
it in reverse and merging the two sub-curves. {\bf Cross} is then used as
the cross section for the extrusion operation.
@\subsubsection{GBOX}
!GBOX
@\begin{verbatim}
PolygonType GBOX( VectorType Point,
VectorType Dx, VectorType Dy, VectorType Dz )
@\end{verbatim}
Create a parallelpiped - Generalized BOX polygonal object, defined by
{\bf Point} as base position, and {\bf Dx, Dy, Dz} as 3 3D vectors to define
the 6 faces of this generalized BOX. The regular BOX object is special case
of GBOX where {\bf Dx} = vector(Dx, 0, 0), {\bf Dy} = vector(0, Dy, 0),
{\bf Dz} = vector(0, 0, Dz).
Note {\bf Dx}, {\bf Dy}, {\bf Dz} must be non-coplanar in order to create a feasible object.
Example:
@\begin{verbatim}
GB = GBOX(vector(0.0, -0.35, 0.63), vector(0.5, 0.0, 0.5),
vector(-0.5, 0.0, 0.5),
vector(0.0, 0.7, 0.0));
@\end{verbatim}
@\subsubsection{GPOLYGON}
!GPOLYGON
@\begin{verbatim}
PolygonType GPOLYGON( GeometryTreeType Object )
@\end{verbatim}
Approximate all Surface(s) in {\bf Object} as polygons using the RESOLUTION
and FLAY4PLY variables. The larger RESOLUTION is the more polygons and
finer the result approximation will be. Each Bezier patch will have roughly
$RESOLUTION^2$ polygons.
FLAT4PLY is a Boolean flag controlling the conversion of an (almost) flat
patch into four (TRUE) or two (FALSE) polygons. Normals are computed to
polygons vertices using surface normal, so Guaroud or Phong rendering can be
performed. Returned is a single polygon object, no matter how complex
{\bf Object} Hierarchy is. Example:
@\begin{verbatim}
Polys = GPOLYGON( list( Srf1, Srf2, Srf3 ) );
@\end{verbatim}
Converts to polygons the three surfaces {\bf Srf1}, {\bf Srf2}, and {\bf Srf3}.
@\subsubsection{GPOLYLINE}
!GPOLYLINE
@\begin{verbatim}
PolylineType GPOLYLINE( GeometryTreeType Object )
@\end{verbatim}
Converts all Surface(s) and Curves(s) in {\bf Object} into polylines using
the RESOLUTION variable. The larger RESOLUTION is the finer the result
approximation will be. Returned is a single polyline object, no matter
how complex {\bf Object} Hierarchy is. Example:
@\begin{verbatim}
Polys = GPOLYLINE( list( Srf1, Srf2, Srf3, list( Crv1, Crv2, Crv3 ) ) );
@\end{verbatim}
converts to polyline the three surfaces {\bf Srf1}, {\bf Srf2}, and {\bf Srf3}
and the three curves {\bf Crv1}, {\bf Crv2}, and {\bf Crv3}.
@\subsubsection{MERGPOLY}
!MERGEPOLY
@\begin{verbatim}
PolygonType MERGEPOLY( ListType PolyList )
@\end{verbatim}
Merge a set of polygonal objects in {\bf PolyList} list to a single polygonal
object. All elements in {\bf ObjectList} must be of PolygonType type. No test
is made on the validity of the data. This function performs the same
operation as the {\bf \verb+^+} operator would, but may be more convenient
to use under some conditions. Example:
@\begin{verbatim}
Vrtx1 = vector( -3, -2, -1 );
Vrtx2 = vector( 3, -2, -1 );
Vrtx3 = vector( 3, 2, -1 );
Vrtx4 = vector( -3, 2, -1 );
Poly1 = poly( list( Vrtx1, Vrtx2, Vrtx3, Vrtx4 ) );
Vrtx1 = vector( -3, 2, 1 );
Vrtx2 = vector( 3, 2, 1 );
Vrtx3 = vector( 3, -2, 1 );
Vrtx4 = vector( -3, -2, 1 );
Poly2 = poly( list( Vrtx1, Vrtx2, Vrtx3, Vrtx4 ) );
Vrtx1 = vector( -3, -2, 1 );
Vrtx2 = vector( 3, -2, 1 );
Vrtx3 = vector( 3, -2, -1 );
Vrtx4 = vector( -3, -2, -1 );
Poly3 = poly( list( Vrtx1, Vrtx2, Vrtx3, Vrtx4 ) );
PolyObj = MERGEPOLY( list( Poly1, Poly2, Poly3 ) );
@\end{verbatim}
@\subsubsection{OFFSET}
!OFFSET
@\begin{verbatim}
CurveType OFFSET( CurveType Crv, NumericType OffsetDistance )
SurfaceType OFFSET( SurfaceType Srf, NumericType OffsetDistance )
@\end{verbatim}
Offsets {\bf Crv} or {\bf Srf}, by translating all control points in the
curve or surface normal, by the {\bf OffsetDistance} amount. Returned curve
or surface only approximates the real offset. One may improve the offset
accuracy using refinement. Negative {\bf OffsetDistance} denotes offset in
the reversed direction of the normal.
Example:
@\begin{verbatim}
OffCrv = OFFSET(Crv, -0.1);
@\end{verbatim}
offsets {\bf Crv} by the amount of $-0.1$ in the reversed normal direction.
@\subsubsection{POLY}
!POLY
@\begin{verbatim}
PolygonType POLY( ListType ObjectList )
@\end{verbatim}
Create a single polygon (and therefore open) object, defined by the
vertices which respectively defined by the objects in {\bf ObjectList} (see LIST).
All elements in {\bf ObjectList} must be of VertorType type. No validity test is
made and it is the user responsibility. see CIRCPOLY for conditions applied to
open objects. Example:
@\begin{verbatim}
V1 = vector( 0.0, 0.0, 0.0 );
V2 = vector( 0.3, 0.0, 0.0 );
V3 = vector( 0.3, 0.0, 0.1 );
V4 = vector( 0.2, 0.0, 0.1 );
V5 = vector( 0.2, 0.0, 0.5 );
V6 = vector( 0.3, 0.0, 0.5 );
V7 = vector( 0.3, 0.0, 0.6 );
V8 = vector( 0.0, 0.0, 0.6 );
V9 = vector( 0.0, 0.0, 0.5 );
V10 = vector( 0.1, 0.0, 0.5 );
V11 = vector( 0.1, 0.0, 0.1 );
V12 = vector( 0.0, 0.0, 0.1 );
I = poly( list( V1, V2, V3, V4, V5, V6, V7, V8, V9, V10, V11, V12 ) );
@\end{verbatim}
constructs an object with a single polygon in the shape of the I letter.
@\subsubsection{RULEDSRF}
!RULEDSRF
@\begin{verbatim}
SurfaceType RULEDSRF( CurveType Crv1, CurveType Crv2 )
@\end{verbatim}
Constructs a ruled surface between the two curves {\bf Crv1} and {\bf Crv2}.
Curves do not have to have the same order or type and will be promoted to
their least common denominator.
Example:
@\begin{verbatim}
Circ = circle( vector( 0.0, 0.0, 0.0 ), 0.25 );
Cyl = RULEDSRF( circ, circ * trans( vector( 0.0, 0.0, 1.0 ) ) );
@\end{verbatim}
Constructs a cylinder of radius 0.25 along the Z axis from 0 to 1.
@\subsubsection{SBEZIER}
!SBEZIER
@\begin{verbatim}
SurfaceType SBEZIER( ListType CtlMesh )
@\end{verbatim}
Creates a Bezier surface out of the provided control mesh. {\bf CtlMesh} is a
list of control points rows, each is a list of control points. All control
points must be of the same type (E2, E3, P2, or P3).
Example:
@\begin{verbatim}
Srf = SBEZIER( list ( list( ctlpt( E3, 0.0, 0.0, 1.0 ),
ctlpt( E3, 0.0, 1.0, 0.0 ),
ctlpt( E3, 0.0, 2.0, 1.0 ) ),
list( ctlpt( E3, 1.0, 0.0, 0.0 ),
ctlpt( E3, 1.0, 1.0, 2.0 ),
ctlpt( E3, 1.0, 2.0, 0.0 ) ),
list( ctlpt( E3, 2.0, 0.0, 2.0 ),
ctlpt( E3, 2.0, 1.0, 0.0 ),
ctlpt( E3, 2.0, 2.0, 2.0 ) ),
list( ctlpt( E3, 3.0, 0.0, 0.0 ),
ctlpt( E3, 3.0, 1.0, 2.0 ),
ctlpt( E3, 3.0, 2.0, 0.0 ) ),
list( ctlpt( E3, 4.0, 0.0, 1.0 ),
ctlpt( E3, 4.0, 1.0, 0.0 ),
ctlpt( E3, 4.0, 2.0, 1.0 ) ) ) );
@\end{verbatim}
@\subsubsection{SBSPLINE}
!SBSPLINE
@\begin{verbatim}
SurfaceType SBSPLINE( NumericType UOrder, NumericType VOrder,
ListType CtlMesh, ListType KnotVectors )
@\end{verbatim}
Creates a Bspline surface out of the provided {\bf UOrder} and {\bf VOrder}
orders, the control mesh {\bf CtlMesh} and the two knot vectors {\bf KnotVectors}.
{\bf CtlMesh} is a list of control points rows, each is a list of control
points. All control points must be of the same type (E2, E3, P2, or P3).
{\bf KnotVectors} is a list of two knot vectors,
each is a list of NumericType knots or a list of a single constant KV\_OPEN or
KV\_FLOAT in which a uniform knot vector with open or floating end condition
will automatically be constructed. Example:
@\begin{verbatim}
Mesh = list ( list( ctlpt( E3, 0.0, 0.0, 1.0 ),
ctlpt( E3, 0.0, 1.0, 0.0 ),
ctlpt( E3, 0.0, 2.0, 1.0 ) ),
list( ctlpt( E3, 1.0, 0.0, 0.0 ),
ctlpt( E3, 1.0, 1.0, 2.0 ),
ctlpt( E3, 1.0, 2.0, 0.0 ) ),
list( ctlpt( E3, 2.0, 0.0, 2.0 ),
ctlpt( E3, 2.0, 1.0, 0.0 ),
ctlpt( E3, 2.0, 2.0, 2.0 ) ),
list( ctlpt( E3, 3.0, 0.0, 0.0 ),
ctlpt( E3, 3.0, 1.0, 2.0 ),
ctlpt( E3, 3.0, 2.0, 0.0 ) ),
list( ctlpt( E3, 4.0, 0.0, 1.0 ),
ctlpt( E3, 4.0, 1.0, 0.0 ),
ctlpt( E3, 4.0, 2.0, 1.0 ) ) );
Srf = SBSPLINE( 3, 3, Mesh, list( list( KV_OPEN ),
list( 3, 3, 3, 4, 5, 6, 6, 6 ) ) );
@\end{verbatim}
constructs a Bspline surface with its first knot vector being uniform with
open end condition.
@\subsubsection{SDIVIDE}
!SDIVIDE
@\begin{verbatim}
SurfaceType SDIVIDE( SurfaceType Srf, ConstantType Direction,
NumericType Param )
@\end{verbatim}
Subdivides a surface into two at the specified parameter value {\bf Param}
in the specified {\bf Direction} (ROW or COL). {\bf Srf} can be either a Bspline
curve in which {\bf Param} must be within surface parametric domain or a Bezier
curve in which {\bf Param} must be in the 0 to 1 range.
Returned is a list of the two sub-surfaces. The individual surfaces may be
extracted from the list using the {\bf NTH} command. Example:
@\begin{verbatim}
SrfLst = SDIVIDE( Srf, ROW, 0.5 );
Srf1 = nth( SrfLst, 1 );
Srf2 = nth( SrfLst, 2 );
@\end{verbatim}
subdivides {\bf Srf} at the parameter value of 0.5 in the ROW direction.
@\subsubsection{SEDITPT}
!SEDITPT
@\begin{verbatim}
SurfaceType SEDITPT( SurfaceType Srf, CtlPtType CPt, NumericType UIndex,
NumericType VIndex )
@\end{verbatim}
Provides a simple mechanism to manually modify a single control point number
{\bf UIndex} and {\bf VIndex} (base count is 0) in {\bf Srf} control mesh
by substituting {\bf CtlPt} instead. CtlPt must have the same point type as
{\bf Srf} points. Original surface {\bf Srf} is not modified. Example:
@\begin{verbatim}
CPt = ctlpt( E3, 1, 2, 3 );
NewSrf = SEDITPT( Srf, CPt, 0, 0 );
@\end{verbatim}
constructs a {NewSrf} with the first control point of {\bf Srf} being
{\bf CPt}.
@\subsubsection{SEVAL}
!SEVAL
@\begin{verbatim}
CtlPtType SEVAL( SurfaceType Srf, NumericType UParam, NumericType VParam )
@\end{verbatim}
Evaluates the provided surface {\bf Srf} at the given {\bf UParam} and
{\bf VParam} values. Both {\bf UParam} and {\bf VParam} should be within
the surface parametric domain if {\bf Srf} is a Bspline surface, or between 0
and 1 if {\bf Srf} is a Bezier surface. Returned control point has the same
type as {\bf Srf} control points. Example:
@\begin{verbatim}
CPt = SEVAL( Srf, 0.25, 0.22 );
@\end{verbatim}
evaluates {\bf Srf} at the parameter values of (0.25, 0.22).
@\subsubsection{SFROMCRVS}
!SFROMCRVS
@\begin{verbatim}
SurfaceType SFROMCRVS( ListType CrvList )
@\end{verbatim}
Construct a surface by substituting the curves in {\bf CrvList} as rows
in a surface control mesh. Curves in {\bf CrvList} are made compatible
by promoting Bezier curves to Bsplines if necessary and raising degree
and refining as required before substituting their control polygons as
rows in the mesh.
The other direction order is the same as the first direction order or
if not enough curves are provided equal to the number of curves in {\bf CrvList}.
The surface will interpolate the first and last curves only. Example:
@\begin{verbatim}
Crv1 = cbspline( 3,
list( ctlpt( E3, 0.0, 0.0, 0.0 ),
ctlpt( E3, 1.0, 0.0, 0.0 ),
ctlpt( E3, 1.0, 1.0, 0.0 ) ),
list( KV_OPEN ) );
Crv2 = Crv1 * trans( vector( 0.0, 0.0, 1.0 ) );
Crv3 = Crv2 * scale( vector( 0.0, 0.0, 2.0 ) )
* trans( vector( 0.1, 0.1, 0.1 ) );
Srf = SFROMCRVS( list( Crv1, Crv2, Crv3 ) );
@\end{verbatim}
@\subsubsection{SNORMAL}
!SNORMAL
@\begin{verbatim}
VectorType SNORMAL( SurfaceType Srf, NumericType UParam, NumericType VParam )
@\end{verbatim}
Computes the normal vector to {\bf Srf} at the parameter values {\bf UParam}
and {\bf VParam}. Example:
@\begin{verbatim}
Tang = SNORMAL( Crv, 0.5, 0.5 );
@\end{verbatim}
computes the normal to {\bf Srf} at the parameter values (0.5, 0.5).
@\subsubsection{SPHERE}
!SPHERE
@\begin{verbatim}
PolygonType SPHERE( VectorType Center, NumericType Radius )
@\end{verbatim}
Creates a SPHERE geometric object, defined by {\bf Center} as SPHERE center,
and with radius {\bf Radius}.
See RESOLUTION for accuracy of SPHERE approximation as polygonal model.
@\subsubsection{SRAISE}
!SRAISE
@\begin{verbatim}
SurfaceType SRAISE( SurfaceType Srf, ConstantType Direction,
NumericType NewOrder )
@\end{verbatim}
Raise {\bf Srf} to the specified {\bf NewOrder} Order in the specified
direction {\bf Direction}. Currently implemented for Bezier surfaces of
any order and linear Bspline surfaces only. Example:
@\begin{verbatim}
Srf = ruledSrf( cbezier( list( ctlpt( E3, -0.5, -0.5, 0.0 ),
ctlpt( E3, 0.5, -0.5, 0.0 ) ) ),
cbezier( list( ctlpt( E3, -0.5, 0.5, 0.0 ),
ctlpt( E3, 0.5, 0.5, 0.0 ) ) ) );
Srf = SRAISE( SRAISE( Srf, ROW, 3 ), COL, 3 );
@\end{verbatim}
construct a bilinear flat ruled surface and raise its both directions to be
quadratic.
@\subsubsection{SREFINE}
!SREFINE
@\begin{verbatim}
SurfaceType SREFINE( SurfaceType Srf, ConstantType Direction,
NumericType Replace, ListType KnotList )
@\end{verbatim}
Provides the ability to {\bf Replace} a knot vector of {\bf Srf} or refine
it in the specified direction {\bf Direction} (ROW or COL).
{\bf KnotList} is a list of knots to refine {\bf Srf} at. All knots should be
within {\bf Srf} parametric domain in {\bf Direction} direction. If knot vector
is to be replaced, the length of {\bf KnotList} should be identical to the length
of {\bf Srf} knot vector in direction {\bf Direction}. If {\bf Srf} is a
Bezier surface, it is automatically promoted to be a Bspline surface.
Example:
@\begin{verbatim}
Srf = SREFINE( SREFINE( Srf,
ROW, FALSE, list( 0.333, 0.667 ) ),
COL, FALSE, list( 0.333, 0.667 ) );
@\end{verbatim}
refines {\bf Srf} in both directions by adding two more knots at 0.333 and
0.667
@\subsubsection{SREGION}
!SREGION
@\begin{verbatim}
SurfaceType SREGION( SurfaceType Srf, ConstantType Direction,
NumericType NewOrder )
@\end{verbatim}
Extracts a subdomain of {\bf Srf} between {\bf MinParam} and {\bf MaxParam}
in the specified {\bf Direction}. Both {\bf MinParam} and {\bf MaxParam}
should be within {\bf Srf} parametric domain in {\bf Direction}.
Example:
@\begin{verbatim}
SubSrf = SREGION( Srf, COL, 0.3, 0.6 );
@\end{verbatim}
extracts the subdomain of {\bf Srf} from the parameter value 0.3 to the
parameter value 0.6 along the COLumn direction. the ROW direction is
extracted as a whole.
@\subsubsection{STANGENT}
!STANGENT
@\begin{verbatim}
VectorType STANGENT( SurfaceType Srf, ConstantType Direction,
NumericType UParam, NumericType VParam )
@\end{verbatim}
Computes the tangent vector to {\bf Srf} at the parameter values {\bf UParam}
and {\bf VParam} in the direction {\bf Direction}. Example:
@\begin{verbatim}
Tang = STANGENT( Srf, ROW, 0.5, 0.6 );
@\end{verbatim}
computes the tangent to {\bf Srf} in the ROW direction at the parameter
values (0.5, 0.6).
@\subsubsection{SURFREV}
!SURFREV
@\begin{verbatim}
PolygonType SURFREV( PolygonType Object )
SurfaceType SURFREV( CurveType Object )
@\end{verbatim}
Create a surface of revolution by rotating the first polygon/curve of the
given {\bf Object}, around the Z axes. No limitation exists on the polygon
(can be non-convex), aside from the requirement for it to be non coplanar
with a plane of the form Z = Const. No limitation exists for the curve. Use
the linear transformation function to position a surface of revolution in a
different orientation. Example:
@\begin{verbatim}
VTailAntn = SURFREV( ctlpt( E3, 0.001, 0.0, 1.0 ) +
ctlpt( E3, 0.01, 0.0, 1.0 ) +
ctlpt( E3, 0.01, 0.0, 0.8 ) +
ctlpt( E3, 0.03, 0.0, 0.7 ) +
ctlpt( E3, 0.03, 0.0, 0.3 ) +
ctlpt( E3, 0.001, 0.0, 0.0 ) );
@\end{verbatim}
constructs a piecewise linear Bspline curve in the XZ plane and use it to
construct a surface of revolution by rotating it around the Z axis.
@\subsubsection{SWEEPSRF}
!SWEEPSRF
@\begin{verbatim}
SurfaceType SWEEPSRF( CurveType CrossSection, CurveType Axis,
NumericType Scale )
SurfaceType SWEEPSRF( CurveType CrossSection, CurveType Axis,
CurveType ScaleCrv )
@\end{verbatim}
Construct a generalized cylinder surface. This function sweeps a specified
cross section {\bf CrossSection} along the provided {\bf Axis}.
The cross section may be constantly scaled (first form above), or scaled
along the Axis parametric domain (second form).
No refinement is performed on any of the curves so scaling and axis
following result is only approximated. Refinement at the proper location
should improve the output accuracy. {\bf ScaleCrv} parametric domain do not
have to match the {\bf Axis} parametric domain and their domains are made
compatible by this function.
Example:
@\begin{verbatim}
Cross = arc( vector( 0.2, 0.0, 0.0 ),
vector( 0.2, 0.2, 0.0 ),
vector( 0.0, 0.2, 0.0 ) ) +
arc( vector( 0.0, 0.4, 0.0 ),
vector( 0.1, 0.4, 0.0 ),
vector( 0.1, 0.5, 0.0 ) ) +
arc( vector( 0.8, 0.5, 0.0 ),
vector( 0.8, 0.3, 0.0 ),
vector( 1.0, 0.3, 0.0 ) ) +
arc( vector( 1.0, 0.1, 0.0 ),
vector( 0.9, 0.1, 0.0 ),
vector( 0.9, 0.0, 0.0 ) ) +
ctlpt( E2, 0.2, 0.0 );
Axis = arc( vector( -1.0, 0.0, 0.0 ),
vector( 0.0, 0.0, 0.1 ),
vector( 1.0, 0.0, 0.0 ) );
Axis = crefine( Arc1, FALSE, list( 0.25, 0.5, 0.75 ) );
ScaleCrv = cbezier( list( ctlpt( E2, 0.0, 0.01 ),
ctlpt( E2, 1.0, 0.5 ),
ctlpt( E2, 2.0, 0.01 ) ) );
Srf = SWEEPSRF( Cross, Axis, ScaleCrv );
@\end{verbatim}
constructs a rounded rectangle cross section and sweep it along an arc while
scaling it so its end points shrink. Note the axis curve {\bf Axis} is
manually refined to better approximate the scaling required.
@\subsubsection{TORUS}
!TORUS
@\begin{verbatim}
PolygonType TORUS( VectorType Center, VectorType Normal,
NumericType MRadius, NumericType mRadius )
@\end{verbatim}
Create a TORUS polygonal object, defined by {\bf Center} as TORUS center,
{\bf Normal} as main TORUS plane normal, {\bf MRadius} as major radius, and
{\bf mRadius} as minor.
See RESOLUTION for accuracy of TORUS approximation as polygonal model.
Example:
@\begin{verbatim}
T = TORUS( vector( 0.0, 0.0, 0.0), vector( 0.0, 0.0, 1.0), 0.5, 0.2 );
@\end{verbatim}
constructs a torus with major plane as the XY plane, major radius of 0.5,
and minor radius of 0.2.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Object transformation functions}
&Object transformation functions
All the routines in this section constructs a 4 by 4 homogeneouos matrix
representing the required transform. These matrices may be concatenated to
achieve a more complex transforms using the matrix multiplication operator
$*$. For example the expression
@\begin{verbatim}
m = trans( vector( -1, 0, 0 ) ) * rotx( 45 ) * trans( vector( 1, 0, 0 ) );
@\end{verbatim}
constructs a transform to rotate an object around the X = 1 line, 45 degrees.
A matrix representing the inverse transform can be computed as:
@\begin{verbatim}
InvM = m ^ -1
@\end{verbatim}
See also overloading the - operator.
@\subsubsection{ROTX}
!ROTX
@\begin{verbatim}
MatrixType ROTX( NumericType Angle )
@\end{verbatim}
Creates a rotation transformation matrix (around X) with {\bf Angle} degrees.
@\subsubsection{ROTY}
!ROTY
@\begin{verbatim}
MatrixType ROTY( NumericType Angle )
@\end{verbatim}
Creates a rotation transformation matrix (around Y) with {\bf Angle} degrees.
@\subsubsection{ROTZ}
!ROTZ
@\begin{verbatim}
MatrixType ROTZ( NumericType Angle )
@\end{verbatim}
Creates a rotation transformation matrix (around Z) with {\bf Angle} degrees.
@\subsubsection{SCALE}
!SCALE
@\begin{verbatim}
MatrixType SCALE( VectorType ScaleFactors )
@\end{verbatim}
Creates a scaling transformation matrix of {\bf ScaleFactors} scaling factors.
@\subsubsection{TRANS}
!TRANS
@\begin{verbatim}
MatrixType TRANS( VectorType TransFactors )
@\end{verbatim}
Creates a translation transformation matrix of {\bf TransFactors} translating
amounts.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{General purpose functions}
&General purpose functions
@\subsubsection{ALIAS}
!ALIAS
@\begin{verbatim}
ALIAS( StringType Name, StringType Value )
@\end{verbatim}
Defines a text substitution: each occurrence of {\bf Name} will be replaced by
the given {\bf Value}. Unlike the rest of the system, this is CASE SENSITIVE.
It is a good practice, therefore, to defines the aliases names to be upper
case, and rest of program including alias values in lower case. For example:
@\begin{verbatim}
ALIAS("ED", "edit(\"file.irt\");");
@\end{verbatim}
defines the alias "ED" to be 'edit("file.irt");'. Note the way the double
quotes are being escaped.
Using "ed" instead of "ED" above will cause infinite loop since "ed"
will be expanded for ever... The aliases will be expanded until line is
too long or 100 expansions occurred in line.
If {\bf Name} is empty string, a list of all defined aliases is printed.
If {\bf Name} is not empty, but {\bf Value} is, that alias is deleted. This is
the only case you need to specify the alias {\bf Name} in LOWER case (otherwise it
will be expanded...) - the alias {\bf Name} comparison is case insensitive.
@\subsubsection{ATTRIB}
!ATTRIB
@\begin{verbatim}
ATTRIB( GeometricType Object, StringType Name, StringType Value )
@\end{verbatim}
Provides a mechanism to add a string attribute to a geometric {\bf Object},
with name {\bf Name} and value {\bf Value}.
These attributes may be used to pass information to other programs about
this object and are saved with the objects in data files. For example
@\begin{verbatim}
ATTRIB(Glass, "rgb", "255,0,0");
@\end{verbatim}
sets the rendered color of the {\bf Glass} object. This specific attribute
provides a finer control on color setting than provided by the color
command, for external programs.
@\subsubsection{BEEP}
!BEEP
@\begin{verbatim}
BEEP( NumericType Frequency, NumericType Time )
@\end{verbatim}
Generates a tone with the given {\bf Frequency} (in Hz), for the given period
of {\bf Time} (in milliseconds). This command is system dependent and may work
differently or not work at all on some systems.
@\subsubsection{CHDIR}
!CHDIR
@\begin{verbatim}
CHDIR( StringType NewPath )
@\end{verbatim}
Change current working directory to NewPath (if exists).
The entry directory is recovered on exit from program.
@\subsubsection{CLOSED}
!CLOSED
@\begin{verbatim}
CLOSED( NumericType Set )
@\end{verbatim}
If {\bf Set} is non zero (see TRUE/FALSE and ON/OFF) then every polygonal
object drawn is assumed to be closed. If a polygonal model is closed every
edge is basically drawn twice - once for each adjacent polygon. If the object
is assumed closed, every such edge will be drawn once only. By default
this option is TRUE.
@\subsubsection{COLOR}
!COLOR
@\begin{verbatim}
COLOR( GeometricType Object, NumericType Color )
@\end{verbatim}
Set the color of the object to one of the specified below. Note that an
object has a default color (see IRIT.CFG file) according to his origin -
loaded with LOAD command, PRIMITIV, or BOOLEAN operation result.
The system internally supports colors (although you may have B\&W system)
and the colors recognized are:
{\bf BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, YELLOW, and WHITE}.
See attrib command for more fine control on colors.
@\subsubsection{COMMENT}
!COMMENT
@\begin{verbatim}
COMMENT
@\end{verbatim}
Two types of comments are allowed:
1. One lines comment: starts anywhere is a line at the '\#' char up to the
end of the line.
2. Block comment: starts by the COMMENT keyword follows by a unique
character (anything but white space), up to the second occurrence of that
character. This is a fast way to comment out large blocks. For example:
@\begin{verbatim}
COMMENT $
This is a comment
$
@\end{verbatim}
@\subsubsection{DIR}
@\begin{verbatim}
DIR( StringType MatchPattern )
@\end{verbatim}
Print the files match the MatchPattern in the current working directory.
MatchPattern may have wild characters as in regular dos DIR - '*', '?'.
This command is only supported under the MSDOS implementation. Example:
@\begin{verbatim}
DIR( "*.irt" );
@\end{verbatim}
lists all the '.irt' files in the current directory.
@\subsubsection{EDIT}
!EDIT
@\begin{verbatim}
EDIT( StringType FileName )
@\end{verbatim}
Invoke the editor (defined in the IRIT.CFG configuration file) as a child
process if the solid modeler. Only one parameter is passed to the editor
which is the FileName to edit. As the solid modeler is still resident, the
child process (the editor) will get only the remained memory - as seen by
the core left.
This command is only supported under the MSDOS implementation.
@\subsubsection{EXIT}
!EXIT
@\begin{verbatim}
EXIT();
@\end{verbatim}
Exits from the solid modeler. NO warning is given!
@\subsubsection{FOR}
@\begin{verbatim}
FOR( NumericType Start, NumericType Increment, NumericType End, AnyType Body )
@\end{verbatim}
Execute the {\bf Body} (see below), while the FOR loop conditions hold.
{\bf Start, Increment, End} are evaluated first and the loop will be executed
while {\bf $<=$ End} if {\bf Increment $>$ 0} or while {\bf $>=$ End} if {\bf Increment $<$ 0}.
If {\bf Start} is of the form "(Variable = Expression)" then that variable is
updated on each iteration, and can be used within the body.
The body may consist of any number of regular commands, separated by
COLONs, including nesting FOR loops to arbitrary level.
No new variables should be introduced in loops - Use only old
variables and/or the iteration variable defined in {\bf Start} (that makes it
a feature now...). Example:
@\begin{verbatim}
FOR ( (b = 100), 100, 300,
FOR ( (a = 100), 100, 2000,
(
beep(a, b)
)
)
);
@\end{verbatim}
exercises the BEEP function in different durations and different frequencies.
This will best work under MSDOS systems.
@\subsubsection{FREE}
!FREE
@\begin{verbatim}
FREE( GeometricType Object )
@\end{verbatim}
Because of the usually huge size of geometric objects, this procedure
may be used to free them. Note however that reassigning a value (even
of different type) will automatically release old allocated space as well.
@\subsubsection{HELP}
!HELP
@\begin{verbatim}
HELP( StringType Subject )
@\end{verbatim}
Provides help on the specified Subject. Example:
@\begin{verbatim}
HELP("");
@\end{verbatim}
will list all {\em IRIT} commands.
@\subsubsection{IF}
@\begin{verbatim}
IF( NumericType Left, StringType Cond, NumericType Right, AnyType Body )
@\end{verbatim}
Executes {\bf Body} (group of regular commands, separated by COLONs - see FOR)
if the condition holds: {\bf Left} and {\bf Right} are evaluated and tested against
the specified condition {\bf Cond} which may be: "$=$", "$>$", "$<$", "$<>$", "$>=$", "$<=$".
Example:
@\begin{verbatim}
resolution = 10;
IF ( machine, "=", msdos, ( resolution = 5 ) );
@\end{verbatim}
sets the resolution to be 10 unless running on an MSDOS system in which the
resolution variable will be set to 5.
@\subsubsection{INCLUDE}
!INCLUDE
@\begin{verbatim}
INCLUDE( StringType FileName )
@\end{verbatim}
Executes the script file {\bf FileName}. Nesting of include file is allowed up
to 10 levels deep. If error occurs, all open files in all nested files
are closed and data is expected at the top level (standard input).
A script file can contain any command the solid modeler supports. Example:
@\begin{verbatim}
INCLUDE( "general.irt" );
@\end{verbatim}
includes the file "general.irt".
@\subsubsection{INTERACT}
!INTERACT
@\begin{verbatim}
INTERACT( GeometryTreeType Object, NumericType UpdateViewMat )
@\end{verbatim}
Invoke interactive mode to manipulate (transform) the given (geometric)
{\bf Object}. {\bf Object} may be any GeometricType or a list of other
GeometryTypes nested to an arbitrary level. {\bf Object} is displayed as
a wire frame. ON SGI 4D systems a rendered display is also available.
If {\bf UpdateViewMat} is non zero (see TRUE/FALSE and ON/OFF) then the
global viewing matrix VIEW\_MAT is updated to the last view from INTERACT.
INTERACT open an interactive menu to rotate/translate/scale an object(s).
Each transformation has zero influence in middle of its box, and maximum
(and opposite) on the box left and right ends.
Screen transformation transforms according to the screen - X is horizontal,
Y vertical, Z into screen. Object transformation transform in object own
coordinate system - you probably want to display AXES object with it (see
AXES).
Left mouse button (return) is used to EXECUTE transformation. Right mouse
button (space bar) is used to ABORT long display in the middle.
On MSDOS, use the numeric keyboard pad (with/without shift) to move if no
mouse available.
If {\bf Object} is a GeometricType, that object is being displayed. If
however it is an ListType the list is recursively traversed and all
geometric objects within the list are displayed. Non geometric object in
the list are ignored.
@\begin{verbatim}
INTERACT( list( Axes, Obj ), FALSE );
@\end{verbatim}
displays and interact with the object {\bf Obj} and the predefined object
{\bf Axes}. VIEW\_MAT will not be updated once INTERACT is done.
@\subsubsection{LIST}
!LIST
@\begin{verbatim}
ListType LIST( AnyType Elem1, AnyType Elem2, ... )
@\end{verbatim}
Constructs an object as a list of several other objects. Only a reference
is made to the Elements, so modifying Elem1 after being included in list,
will affect Elem1 in that list, next time list is used!
Each inclusion of an object in a list increases its internal {\bf used}
reference. The object is freed iff in {\bf used} reference is zero.
As a result, attempt to delete a variable (using FREE) which is referenced
in a list will remove the variable, but the object itself will be freed only
when that list will be freed.
@\subsubsection{LOAD}
!LOAD
@\begin{verbatim}
AnyType LOAD( StringType FileName )
@\end{verbatim}
Load the object from the given {\bf FileName}. The object may be any object
defined in the system, including lists, in which the structure is
loaded recursively and reconstructed as well (internal objects are
inserted into the global system object list if have names defined).
If no file type is provided, ".dat" is assumed.
@\subsubsection{LOGFILE}
!LOGFILE
@\begin{verbatim}
LOGFILE( NumericType Set )
@\end{verbatim}
If {\bf Set} is non zero (see TRUE/FALSE and ON/OFF) then everything printed in
the input window, will go to the log file specified in IRIT.CFG configuration
file. This file will be created the first time logfile is turned ON.
@\subsubsection{NORMAL}
!NORMAL
@\begin{verbatim}
NORMAL( NumericType Set, NumericType Size, NumericType Color )
@\end{verbatim}
If {\bf Set} is non zero (see TRUE/FALSE and ON/OFF) then the normals to the
objects are also displayed. Normals should always point INTO the object.
{\bf Size} sets the length of the normals, and {\bf Color} their color.
See COLOR command for legal colors.
@\subsubsection{NTH}
@\begin{verbatim}
AnyType NTH( ListType ListObject, NumericType Index )
@\end{verbatim}
Returns the {\bf Index} (base count 1) element of the list {\bf ListObject}.
Example:
@\begin{verbatim}
Lst = list( a, list( b, c ), d );
Lst2 = NTH( Lst, 2 );
@\end{verbatim}
and now {\bf Lst2} is equal to 'list( b, c )'.
@\subsubsection{PAUSE}
!PAUSE
@\begin{verbatim}
PAUSE( NumericType Flush )
@\end{verbatim}
Waits for a keystroke. Nice to have if temporary stopping in middle of
included file (see INCLUDE) is needed. If {\bf Flush} is TRUE then the input
is first flushed to guarantee we will wait.
The implementation of this function is machine dependent and is geared
mainly for MSDOS.
@\subsubsection{SAVE}
!SAVE
@\begin{verbatim}
SAVE( StringType FileName, AnyType Object )
@\end{verbatim}
Saves the provided {\bf Object} into specified file {\bf FileName}. No extension type
is needed (ignored if specified), and ".dat" is always used. {\bf Object} can
be any object type including list, in which structure is saved recursively.
See also LOAD.
@\subsubsection{SNOC}
!SNOC
@\begin{verbatim}
SNOC( AnyType Object, ListType ListObject )
@\end{verbatim}
Similar to the lisp cons operator but puts the new {\bf Object} in the {\em end}
of the list {\bf ListObject} instead of the beginning, in place. Example:
@\begin{verbatim}
Lst = list( axes );
SNOC( Srf, Lst );
@\end{verbatim}
and now {\bf Lst} is equal to the list 'list( axes, Srf )'.
@\subsubsection{SYSTEM}
!SYSTEM
@\begin{verbatim}
SYSTEM()
@\end{verbatim}
Invoke the current command processor (usually COMMAND.COM) as defined by
the COMSPEC environment variable. As the solid modeler is still resident,
the child process (the command processor) will get only the remained memory
- as seen by the core left.
This command is only supported under the MSDOS implementation.
@\subsubsection{TIME}
!TIME
@\begin{verbatim}
TIME( NumericType Reset )
@\end{verbatim}
Returns the real time (in seconds) from the last time TIME was called with
{\bf Reset} TRUE. Note this is real time and not cpu time so running in a multi
tasked system will return values, which not necessarily reflects this program
execution time. As mentioned above if {\bf Reset} is non zero the time count is
reset. The time is automatically reset to beginning of execution of this
program, when the program is first invoked.
Since this is real type, it may be unusable for multitasked systems.
Example:
@\begin{verbatim}
Time1 = TIME( TRUE );
.
.
.
Time1 = TIME( FALSE );
DumpLvl = 1;
Time1;
@\end{verbatim}
prints the time in seconds between the above two time function calls.
@\subsubsection{VARLIST}
!VARLIST
@\begin{verbatim}
VARLIST()
@\end{verbatim}
List all the currently defined objects in the system.
@\subsubsection{VECTOR}
!VECTOR
@\begin{verbatim}
VectorType VECTOR( NumericType Operand1, NumericType Operand2,
NumericType Operand3 )
@\end{verbatim}
Creates a vector type object, out of 3 NumericType scalars.
@\subsubsection{VIEW}
!VIEW
@\begin{verbatim}
VIEW( GeometricTreeType Object, NumericType ClearWindow )
@\end{verbatim}
Display the (geometric) object(s) as given in {\bf Object}. See INTERACT
for more on {\bf Object}.
If {\bf ClearWindow} is non zero (see TRUE/FALSE and ON/OFF) the window is
first cleared (before drawing the objects).
The global viewing matrix VIEW\_MAT is used as the transformation matrix.
Example:
@\begin{verbatim}
VIEW( Axes, FALSE );
@\end{verbatim}
displays the predefined object {\bf Axes} in the viewing window on top of
what was drawn there.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{System variables}
&System variables
System variables are predefined objects in the system. Any time {\em IRIT} is
executed, these variable will exist and be set to values which are sometimes
machine dependent. These are {\em regular} objects in any other sense
including the ability to delete or overwrite them. One can modify, delete
or introduce other objects by the use of the IRITINIT.IRT file.
@\subsubsection{AXES}
!AXES
Predefined polyline object (PolylineType) that holds XYZ axes system. May be
viewed.
@\subsubsection{DRAWCTLPT}
!DRAWCTLPT
Predefined Boolean variable (NumericType) controlling whether curves control
polygons and surfaces control meshes will be drawn (TRUE) or not (FALSE).
@\subsubsection{DUMPLVL}
!DUMPLVL
Content of objects assigned to variables may be displayed by executing the
command 'objname;' where objname is the name of the object. This variable
(NumericType) control the way the data is dumped as follows:
# 20 2 1 1
DumpLvl $>=$ 0
Only object names/types are printed.
DumpLvl $>=$ 1
Non geometric object values are dumped.
DumpLvl $>=$ 2
Curves and Surfaces are dumped.
DumpLvl $>=$ 3
Polygons/lines are dumped.
DumpLvl $>=$ 4
List objects are traversed recursively.
@\subsubsection{ECHOSRC}
!ECHOSRC
Predefined Boolean variable (NumericType) controlling echoing of
interpreted commands to screen (TRUE) or not (FALSE).
@\subsubsection{FLAT4PLY}
!FLAT4PLY
Predefined Boolean object (NumericType) controlling the way almost flat
surface patches are converted to polygons: four polygons (TRUE) or only
two polygons (FALSE).
@\subsubsection{INTERCRV}
!INTERCRV
Predefined numeric object (NumericType) that if TRUE the Boolean geometry
operators return the intersection curves instead of the result model.
Its default value is FALSE.
@\subsubsection{INTERNAL}
!INTERNAL
Predefined Boolean object (NumericType) that if not zero enables displaying
internal polygon edges (edges created by the convex polygon splitting for
example). One usually does not want to see these edges, and its default
value is FALSE.
@\subsubsection{MACHINE}
!MACHINE
Predefined numeric object (NumericType) holding machine type as one of the
following constants: MSDOS, SGI, HP, SUN, APOLLO, UNIX.
@\subsubsection{RESOLUTION}
!RESOLUTION
Predefined numeric object (NumericType) that sets the accuracy of the
primitive geometric objects generated. Holds the number of divisions a
circle is divided into (with minimum value of 4). If, for example, is set
to 6, then a CONE generated, will effectively be 6 sided pyramid.
Also controls the fineness freeform curves and surfaces are approximated
as piecewise linear polylines (for display purposes for example), and the
fineness freeform surfaces are approximated as polygons.
@\subsubsection{VIEW\_MAT}
!VIEW_MAT
Predefined matrix object (MatrixType) to hold the viewing matrix used/set
by VIEW and/or INTERACT.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{System constants}
&System constants
The following constants are used by the various functions of the system to
signal certain conditions. Internally, they are represented numerically
although, in general, their exact value is unimportant and may be changed
in future versions. In the rare situation you would like to know their
values, here is a sequence that will allow you to do so:
@\begin{verbatim}
DumpLvl = 1;
A = BLUE;
A;
@\end{verbatim}
in other words, assign the constant to a variable and display its content.
@\subsubsection{APOLLO}
!APOLLO
A constant designates an APOLLO system in the MACHINE variable.
@\subsubsection{BLACK}
!BLACK
A constant defining a BLACK color.
@\subsubsection{BLUE}
!BLUE
A constant defining a BLUE color.
@\subsubsection{COL}
A constant defining the COLumn direction of a surface mesh.
@\subsubsection{CYAN}
!CYAN
A constant defining a CYAN color.
@\subsubsection{E2}
A constant defining an E2 (X and Y coordinates) control point type.
@\subsubsection{E3}
A constant defining an E3 (X, Y, and Z coordinates) control point type.
@\subsubsection{FALSE}
!FALSE
A zero constant. May be used as Boolean operand.
@\subsubsection{GREEN}
!GREEN
A constant defining a GREEN color.
@\subsubsection{HP}
A constant designates an HP system in the MACHINE variable.
@\subsubsection{KV\_FLOAT}
!KV_FLOAT
A constant defining a floating end condition uniform knot vector.
@\subsubsection{KV\_OPEN}
!KV_OPEN
A constant defining an open end condition uniform knot vector.
@\subsubsection{MAGENTA}
!MAGENTA
A constant defining a MAGENTA color.
@\subsubsection{MSDOS}
!MSDOS
A constant designates an MSDOS system in the MACHINE variable.
@\subsubsection{OFF}
Synonym of FALSE.
@\subsubsection{ON}
Synonym for TRUE.
@\subsubsection{P2}
A constant defining an P2 (X, Y, and W coordinates) rational control point
type.
@\subsubsection{P3}
A constant defining an P3 (X, Y, Z, and W coordinates) rational control
point type.
@\subsubsection{PI}
The constant of 3.141592...
@\subsubsection{RED}
A constant defining a RED color.
@\subsubsection{ROW}
A constant defining the ROW direction of a surface mesh.
@\subsubsection{SGI}
A constant designates a SGI system in the MACHINE variable.
@\subsubsection{SUN}
A constant designates a SUN system in the MACHINE variable.
@\subsubsection{TRUE}
!TRUE
A non zero constant. May be used as Boolean operand.
@\subsubsection{UNIX}
!UNIX
A constant designates a generic UNIX system in the MACHINE variable.
@\subsubsection{WHITE}
!WHITE
A constant defining a WHITE color.
@\subsubsection{YELLOW}
!YELLOW
A constant defining a YELLOW color.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{poly3d - A Data Display Program}
!poly3d - A Data Display Program
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Introduction}
&Introduction
poly3d is a display program for data files created by the {\em IRIT} solid
modeler. Data can be displayed on almost any IBMPC graphic device that has
Borland's BGI support, for the MSDOS BC++ port, or using any device driver
that is supported by DJGPP, in the MSDOS DJGPP port.
Under UNIX systems both MIT's X11 and SGI's GL are supported.
On SGI's, solid smooth shading is available via normal computation
support. Displayed images may be saved as postscript files as well as GIF
images (if poly3d was built with GIF support).
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Command Line Options}
&Command line options
@\begin{verbatim}
poly3d [-c] [-m] [-i] [-e #Edges] [-n] [-N] [-M] [-I n] [-P] [-S n]
[-f FineNess] [-4] [-z] DFiles
@\end{verbatim}
@\begin{itemize}
@\item
{\bf -c}: Closed object - if an object is closed (such as objects created by
{\em IRIT} solid medeller) each edge is actually displayed twice - once
for each adjacent polygon. This flag will ensure every edge will be
displayed only once.
@\item
{\bf -m}: More - provide some more information on the data file(s) parsed.
@\item
{\bf -i}: Internal edges (created by {\em IRIT}) - default is not to display them, and
this option will force displaying them as well.
@\item
{\bf -e n}: \# Edges to use from each given polygon (default all). Very handy to
do '-e 2 -4-' or '-e 1 -4' on polygons created from a freeform surface.
@\item
{\bf -n}: Draw vertex normals if data file has them.
@\item
{\bf -N}: Draw polygon normals if data file has them (PLANE definition).
@\item
{\bf -M}: Draw the surfaces control mesh/curves control polygons as well.
@\item
{\bf -I n}: Specify number of isolines per surface.
@\item
{\bf -P}: Generate polygonal approximation for surfaces instead of isolines.
@\item
{\bf -S n}: Specify the log based 2 of number of samples per curve.
@\item
{\bf -f FineNess}: Controls the fineness of the surface to polygon subdivision.
This number is log based 2 of roughly the number of subdivisions of
the surface in each axes (see cagd\_lib for more).
@\item
{\bf -4}: Force four polygons per flat bilinear in surface to polygon
conversion. Otherwise two polygons only.
@\item
{\bf -z}: Print version number and current defaults.
@\end{itemize}
Some of the options may be turned on in poly3d.cfg. They can be then turned
off in the command line as -?-.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Configuration}
&Configuration
The program can be configured using a configuration file named poly3d.cfg.
The appropriate configuration file should be copied into poly3d.cfg:
Under MSDOS BC++ its poly3dms.cfg, under MSDOS DJGPP its poly3ddj.cfg, and
under UNIX its poly3dun.cfg.
This is a plain ascii file you can edit directly and set the parameters
according to the comments there. Executing 'poly3d -z' will show the
current configuration as read from the configuration file.
MSDOS version only:
The configuration file in MSDOS BC++ system can be in any directory which
is in your path - the same place as the executable is probably a good choice.
The program supports SuperVGA, VGA/EGA, CGA \& HERCULES graphics card, and
uses the Turbo C autodetect feature. If this fails you can always coerce it
to a specific card - see the poly3d.cfg file. For a SuperVGA you will need to
provide your own BGI driver.
The program will use 80x87 if it detects one - again uses the Turbo C 80x87
autodetect, or will run (much!) slower without it...
The MSDOS DJGPP port can be used with any graphics driver that DJGPP
support. If not 80x87 is present, the emulator, emu387, must be used.
In both the BC++ and DJGPP ports, a mouse or a joystick may be used
if properly selected in poly3d.cfg configuration file.
A windowing library, called intr\_lib is used (for both BC++ and DJGPP)
for the interaction and windows which can be resized/moved/poped/pushed etc.
via a default setting as selected by the configuration file and modified via
a pop up menu during a session. see Irit solid modeler for more on intr\_lib
and the interface.
UNIX version only:
The configuration file is being searched in the IRIT\_PATH environment
variable under UNIX hosts. For example 'setenv IRIT\_PATH /u/gershon/irit/bin/'.
Note IRIT\_PATH must terminate with '/'. If the variables is not set only
the current directory is being searched.
Add the following options to your {\em .Xdefaults} if you use X11. Most options
set are self explanatory. The Trans attributes control the transformation
window, while View control the view window. SubWin control the subwindows
within the Transformation window:
# 33 2 0 1
poly3d*Trans*BackGround:
NavyBlue
poly3d*Trans*BorderColor:
Red
poly3d*Trans*BorderWidth:
poly3d*Trans*TextColor:
Yellow
poly3d*Trans*SubWin*BackGround:
DarkGreen
poly3d*Trans*SubWin*BorderColor:
Magenta
poly3d*Trans*Geometry:
=150x500+500+0
poly3d*Trans*CursorColor:
Green
poly3d*View*BackGround:
NavyBlue
poly3d*View*BorderColor:
Red
poly3d*View*BorderWidth:
poly3d*View*Geometry:
=500x500+0+0
poly3d*View*CursorColor:
Red
Note the above options are the same as for the irit solid modeler
itself.
If poly3d is used under SGI gl library, you can set the prefered windows
location in poly3d.cfg. No color control is provided at this time.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Usage}
&Usage
The program is controlled via a transformation menu. The object can be
rotated, translated, or scaled in screen or object based corrdinate system
and with orthographic or perspective projected.
Two operations are fundamental to the operation of poly3d:
# 10 2 0 1
EXECUTE
$<$Return$>$ key on the keyboard, or left mouse button if exists.
ABORT
$<$Space$>$ key on the keyboard, or right mouse button if exists.
The cursor may be moved via a mouse (if exists) or using the numeric
keypad/arrows (shifted for faster movement).
The ABORT may be useful in large data sets when another
transformation should be applied with no need to wait to the current one to
complete.
The menus work in two modes in all implementations. If you click the
EXECUTE button once on a transformation subwindow, that transformation
will be applied. Most transformation subwindows have vertical bars in
the middle. If the cursor is on the vertical bar the {\em amout} of
transformation applied is {\em zero}. If the cursor is on the leftmost side
of the subwindow, the {\em amount} will be maximized and if the cursor is on
the rightmost side, the transformation {\em amount} will be maximized to the
other direction (inverse transform).
In addition, if one clicks the mouse (with the affect as above) but hold
the EXECUTE button while dragging, continuous transformation will be applied.
Altough implemented in all systems, you would probably like to try this on
very simplistic models on slow machines.
Keyboard control support is for MSDOS systems only.
@\subsection{Output Files}
&Output Files
poly3d can save viewing matrices (to be used by poly3d-h, poly3d-r, or
irit2ray for example), postscript files of the current view and GIF images
of the screen if poly3d was built with GIF support.
The postscript file can be directly sent to a laser printer. The viewing
matrix should be appended {\em after} the data when any program is to use
it. The last viewing matrix in the data will be the one used. For example
@\begin{verbatim}
irit2ray -l -f 20 b58.dat generic0.mat
@\end{verbatim}
where generic0.mat is the matrix saved bu poly3d.
All files will be named genericX.EXT where EXT can be one of '.mat', '.ps'
and '.gif' respectively. X is single digit so up to 10 distinguished files
of each type can be saved each time.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{poly3d-h - Hidden Line Removing Program}
!poly3d-h - Hidden Line Removing Program
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Introduction}
&Introduction
poly3d-h is a program to remove hidden line of a given polygonal model.
Freeform objects are preprocessed into polygons with controlled fineness.
The program performes 4 passes over the input:
1. Preprocesses and maps all polgons in scene, and sorts them.
2. Generates edges out of the polygonal model and sorts them (preprocesing
for the scan line algorithm) into buckets.
3. Intersects edges, and splits edges with non homogeneous visibility (the
scan line algorithm)
4. Applies a visibility test of each edge.
This programs can handle CONVEX polygons only. From {\em IRIT} one can
ensure a model is consisting of convex polygons only by the CONVEX command:
@\begin{verbatim}
CnvxObj = convex( Obj );
@\end{verbatim}
just before saving it into a file. Surfaces are always decomposed into
triangles only.
poly3d-h output is of the form of polylines. It is a regular {\em IRIT} data
file that can be viewed using poly3d, for example.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Command Line Options}
&Command line options
@\begin{verbatim}
poly3d-h [-b] [-m] [-i] [-e #Edges] [-f FineNess] [-4] [-z] DFiles [> OutFile]
@\end{verbatim}
@\begin{itemize}
@\item
{\bf -b}: BackFacing - if object is closed (such as most models created by {\em IRIT})
back facing polygons will be deleted, and therefore speed up the
process by at list factor of two.
@\item
{\bf -m}: More - provide some more information on the data file(s) parsed.
@\item
{\bf -i}: Internal edges (created by {\em IRIT}) - default is not to display them, and
this option will force displaying them as well.
@\item
{\bf -e n}: \# Edges to use from each given polygon (default all). Very handy
as '-e 1 -4' for freeform data.
@\item
{\bf -f FineNess}: Controls the fineness of the surface to polygon subdivision.
This number is log based 2 of roughly the number of subdivisions of
the surface in each axes (see cagd\_lib for more).
@\item
{\bf -4}: Force four polygons per flat bilinear in surface to polygon
conversion. Otherwise two polygons only.
@\item
{\bf -z}: Print version number and current defaults.
@\end{itemize}
Some of the options may be turned on in poly3d-h.cfg. They can be then
turned off in the command line as -?-.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Configuration}
&Configuration
The program can be configured using a configuration file named poly3d-h.cfg.
This is a plain ascii file you can edit directly and set the parameters
according to the comments there. executing 'poly3d-h -z' will show the
current configuration as read from the configuration file.
UNIX and MSDOS DJGPP versions only:
The configuration file is being searched in the IRIT\_PATH environment
variable. For example 'setenv IRIT\_PATH /u/gershon/irit/bin/'.
Note IRIT\_PATH must terminate with '/'. If the variables is not set only
the current directory is being searched.
MSDOS BC++ version only:
The configuration file in MSDOS system can be in any directory which is in
your path - the same place as the executable is probably a good choice.
The program will use 80x87 if it detects one - uses the Turbo C 80x87
autodetect, or will run (much!) slower without it...
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Usage}
&Usage
As this program is not interactive, usage is quite simple, and only
control available is using the command lines options.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{poly3d-r - A Simple Data Rendering Program}
!poly3d-r - A Simple Data Rendering Program
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Introduction}
&Introduction
poly3d-r is a simple rendering program for data files created by the {\em IRIT}
solid modeler. poly3d-r generates GIF images with 8 bits per pixel. As a result
rendered images are of medium quality. Although reasonably fast, one should
use one of several raytracing public domain programs available (such as
RAYSHADE which irit2ray can generate data to) for high quality images.
poly3d-r uses cosine shading approximation, and flat/Gouraud interpolation.
The program performes 4 passes over the input:
1. Process the input (parsing.)
2. Prepare the polygons by sorting them by their Y after mapping then into
screen space.
3. Evaluate colors for vertices (using polygon normals if flat shading, or
by vertex normals for Gouraud shading).
4. Scan the data by scan line basis and dump out image.
This programs can handle CONVEX polygons only. From {\em IRIT} one can
ensure a model is consisting of convex polygons only by the CONVEX command:
@\begin{verbatim}
CnvxObj = convex( Obj );
@\end{verbatim}
just before saving it into a file. Surfaces are always decomposed into
triangles only.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Command Line Options}
&Command line options
@\begin{verbatim}
poly3d-r [-a Ambient] [-c N] [-l X Y Z] [-2] [-m] [-s Xsize Ysize]
[-S SubSample] [-g] [-b] [-M Mask] [-f FineNess] [-z] DFiles > Image.gif
@\end{verbatim}
@\begin{itemize}
@\item
{\bf -a Ambient}: Sets the ambient intensity (must be in [0.0..1.0] range).
@\item
{\bf -c N}: number of bits per pixel N (must be in [1..8] range).
@\item
{\bf -l X Y Z}: specify the light source normal direction. This vector does not
to be unit vector. Only one light source is supported.
@\item
{\bf -2} : Force emulation of 2 light sources at opposite directions as selected
via [-l]. This may be useful for models that has no plane specified (i.e.
model has no PLANE attribute for its polygons), as the program guess the
equation from the points themselves, and which can be to the opposite
direction.
@\item
{\bf -m}: More - provide some more information on the data file(s) parsed.
@\item
{\bf -s Xsize Ysize}: specify image dimensions. As the models created by {\em IRIT}
are mapped to a unit domain (X in [-1..1], Y in [-1..1]) by the
viewing matrix, objects must be scaled up. The scaling up factor is
MIN(Xsize, Ysize), which guarantee nothing of the original image will be
clipped.
@\item
{\bf -b}: Purge back facing polygons. If the scene contains closed objects (such
as the ones usually created by {\em IRIT}), the back facing polygons can be
deleted. This would not change the image, but will speed up the process
at about %15. Using this option for non complete boundary object and/or
objects with polygons with no PLANE specified would almost definitely
create wrong image.
@\item
{\bf -g}: Use Gouraud shading interpolation (flat shading is used by default).
This is somewhat slower, but gives nicer results.
@\item
{\bf -S SubSample}: sub sample, and uses box filter to low pass filter the
image, using SubSample as grid side of SubSample by SubSample.
This obviously make things slower, but guess what - it looks much better.
@\item
{\bf -M Mask}: Create a new GIF file named Mask that is a binary image set to 1
at any pixel covered by one of the objects or 0 otherwise. As a color of
an object can become equal to the background at some point, there is no
way to find whether pixel is background or an object in the background
color. The Mask can be used instead. This Mask can be used when combining
images (such as gifcomp utility in the gif\_lib).
This image is a binary alpha channel.
@\item
{\bf -f FineNess}: Controls the fineness of the surface to polygon subdivision.
This number is log based 2 of roughly the number of subdivisions of
the surface in each axes (see cagd\_lib for more).
@\item
{\bf -z}: Print version number and current defaults.
@\end{itemize}
The image is dumped to stdout as a GIF image which can be redirected to a
file or to be piped to any program that reads GIF images from stdin.
Some of the options may be turned on in poly3d-r.cfg. They can be then
turned off in the command line as -?-.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Configuration}
&Configuration
The program can be configured using a configuration file named poly3d-r.cfg.
This is a plain ascii file you can edit directly and set the parameters
according to the comments there. executing 'poly3d-r -z' will show the
current configuration as read from the configuration file.
UNIX and MSDOS DJGPP versions only:
The configuration file is being searched in the IRIT\_PATH environment
variable. For example 'setenv IRIT\_PATH /u/gershon/irit/bin/'.
Note IRIT\_PATH must terminate with '/'. If the variables is not set only
the current directory is being searched.
MSDOS BC++ version only:
The configuration file in MSDOS system can be in any directory which is in
your path - the same place as the executable is probably a good choice.
The program will use 80x87 if it detects one - uses the Turbo C 80x87
autodetect, or will run (much!) slower without it...
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Usage}
&Usage
As this program is not interactive, usage is quite simple, and only
control available is using the command lines options.
Some Remarks:
1. If the input file is degenerate (2 vertices are identical etc.) they
will be ignored is the next passes. Use [-m] if you want to know about
them.
2. The color of the object can be extract via the COLOR attribute as set
via the {\em IRIT} COLOR command. In addition to this fixed set of colors, one
can specify the color in RGB space using the ATTRIB command. For example:
@\begin{verbatim}
attrib( Srf17, "rgb", "255,155,55" );
@\end{verbatim}
Each of R G B must be integer is the range [0..255].
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{Irit2Ray - IRIT To RAYSHADE filter}
!IRIT2RAY - IRIT To RAYSHADE filter
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Command Line Options}
&Command line options
@\begin{verbatim}
irit2ray [-l] [-4] [-G GridSize] [-f FineNess] [-o OutName] [-g] [-z] DFiles
@\end{verbatim}
@\begin{itemize}
@\item
{\bf -l}: Linear - forces linear (degree two) surfaces to be approximated
as a single polygon along their linear direction.
Although most of the time, linear direction can be exactly represented
using a single polygon, even a bilinear surface can have a free form
shape (saddle like) that is not representable using a single polygon.
Not using this option will better emulate the surface shape but
will create unnecessary polygons in cases where one is enough.
@\item
{\bf -4}: Four - Generate four polygons per flat patch. Default is 2.
@\item
{\bf -G GridSize}: Usually objects are grouped as {\em lists} of polygons.
This flags will coerce the usage of RAYSHADE {\em grid} constructure,
with {\em GridSize} being used as the grid size along the object bounding
box largest dimension.
@\item
{\bf -f FineNess}: An integer value controling the fineness of surface to
polygons process. Roughly speaking it will set to the number of polygons
along one Bezier patch direction. A Bezier patch will have order of
$FineNess^2$ polygons then. The Order of the surface also affect the
amount of polygons; The higher the order is, more polygons are created.
A B-spline surface is first converted into piecewise Bezier to make
sure C1 discontinuities will show up in the polygonal approximation.
@\item
{\bf -o OutName}: Name of output files. By default the name of the first data
file from {\em DFiles} list is used. See below on the output files.
@\item
{\bf -g}: Generates the geometry file only. See below.
@\item
{\bf -z}: Print version number and current defaults.
@\end{itemize}
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Usage}
&Usage
Irit2Ray converts freeform surfaces into polygons in format that can
be used by RAYSHADE. Two files are created, one with '.geom' extension and
one with '.ray'. Since the number of polygons can be extremely large,
the geometry is isolated in the '.geom' and is included (via '\#include') in
the main '.ray' file. The later holds the surface properties for all the
geometry as well as viewing and RAYSHADE specific commands. This allows
changing shading or viewing properties while editing small ('.ray') files.
If '-g' is specified, only the '.geom' file is created, preserving the
current '.ray' file.
In practice it may be useful to create a low resolution approximation
of the model, change viewing/shading parameters in the '.ray' file until
a good view and/or surface quality is found and then run Irit2Ray once more
to create a high resolution approximation of the geometry using '-g'.
Here is a simple example:
@\begin{verbatim}
irit2ray -l -f 5 b58.dat
@\end{verbatim}
creates b58.ray and b58.geom with low resolution (FineNess of 5).
At such low resolution it can very well may happen that triangles will have
normals "over the edge" since a single polygon may approximate a highly
curves surface. That will cause rayshade to issue an
"Inconsistant triangle normals" warning. This problem will not exist if
high fineness is used.
One can ray trace this scene using a command similar to:
@\begin{verbatim}
rayshade -p -W 256 256 b58.ray > b58.rle
@\end{verbatim}
Once done with parameter setting for rayshade, a fine approximation of the
model can be created with:
@\begin{verbatim}
irit2ray -l -g -f 25 b58.dat
@\end{verbatim}
which will only recreate b58.geom (becuase of the -g option).
Each time a data file is saved in {\em IRIT}, it can be saved with the viewing
matrix of the last INTERACT by saving the VIEW\_MAT object as well. I.e.:
@\begin{verbatim}
save( "b58", list( view_mat, b58 ) );
@\end{verbatim}
However one can overwrite the viewing matrix by appending a new matrix in the
end of the command line, created by poly3d:
@\begin{verbatim}
poly3d b58.dat
irit2ray -l -f 5 b58.dat generic0.mat
@\end{verbatim}
where generic0.mat is the viewing matrix created by poly3d.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Advanced Usage}
&Advanced Usage
One can specify surface qualities for individual surfaces of a model.
Several such attributes are supported by Irit2Ray and can be set within {\em IRIT}.
See also the ATTRIB {\em IRIT} command.
If a certain surface should be finer than the rest of the scene, one can
set a "resolution" attribute which specifies the {\em relative} FineNess resolution
of this specific surface. For example:
@\begin{verbatim}
attrib( srf1, "resolution", 2 );
@\end{verbatim}
will force srf1 to have twice the default resolution, as set via the '-f'
flag.
Almost flat patches are converted to polygons. The rectangle can be
converted into two polygons (by subdividing along one of its diagonals) or
into four by introducing a new point at the patch center. This behaviour is
controlled by the '-4' flag, but can be overwritten for individual surfaces
bu setting "twoperflat" or "fourperflat".
RAYSHADE specific properties are controlled via the following attributes:
"specpow", "reflect", "transp", "body", "index", and "texture". Refer to
RAYSHADE manual for their meaning. For example:
@\begin{verbatim}
attrib( srf1, "transp", "0.3" );
attrib( srf1, "texture", "wood" );
@\end{verbatim}
Surface color is controlled in two levels. If the object has an RGB
attribute it is used. Otherwise a color as set via {\em IRIT} COLOR command
is being used if set. The later allowes you to specify only the 3 additive,
3 substractive and white and black and so is very limited for rendering
purposes. Example:
@\begin{verbatim}
attrib( tankBody, "rgb", "244,164,96" );
@\end{verbatim}
Current implementation allows white spaces in neither the attribute
name nor in the attribute value.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{Irit2Nff - IRIT To NFF filter}
!IRIT2NFF - IRIT To NFF filter
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Command Line Options}
&Command line options
@\begin{verbatim}
irit2nff [-l] [-4] [-c] [-f FineNess] [-o OutName] [-g] [-z] DFiles
@\end{verbatim}
@\begin{itemize}
@\item
{\bf -l}: Linear - forces linear (degree two) surfaces to be approximated
as a single polygon along their linear direction.
Although most of the time, linear direction can be exactly represented
using a single polygon, even a bilinear surface can have a free form
shape (saddle like) that is not representable using a single polygon.
Not using this option will better emulate the surface shape but
will create unnecessary polygons in cases where one is enough.
@\item
{\bf -4}: Four - Generate four polygons per flat patch. Default is 2.
@\item
{\bf -c}: Output files should be filtered by cpp. By doing so, the usually
huge geometry file is seperated from the main nff file that contains
the surface properties and view parameters. By default all data,
including the geometry, is saved into a single file with type extension
'.nff'. Use of '-c' will pull out all the geometry into a file with
the same name but '.geom' extension and which will be included using
'\#include' command. The '.nff' file should, in that case, be
preprocessed using cpp before piped into the nff renderer.
@\item
{\bf -f FineNess}: An integer value controling the fineness of surface to
polygons process. Roughly speaking it will set to the number of polygons
along one Bezier patch direction. A Bezier patch will have order of
$FineNess^2$ polygons then. The Order of the surface also affect the
amount of polygons; The higher the order is, more polygons are created.
A B-spline surface is first converted into piecewise Bezier to make
sure C1 discontinuities will show up in the polygonal approximation.
@\item
{\bf -o OutName}: Name of output files. By default the name of the first data
file from {\em DFiles} list is used. See below on the output files.
@\item
{\bf -g}: Generates the geometry file only. See below.
@\item
{\bf -z}: Print version number and current defaults.
@\end{itemize}
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Usage}
&Usage
Irit2Nff converts freeform surfaces into polygons in format that can
be used by NFF renderer. Usually one file is created with '.nff' type
extension. Since the number of polygons can be extremely large, a '-c'
option is provided and which separate the geometry from the surface
properties and view specification but requires preprocessing by cpp.
The geometry is isolated in a file with extension '.geom' and included
(via '\#include') in the main '.nff' file. The later holds the surface
properties for all the geometry as well as the viewing specification.
This allows changing shading or viewing properties while editing small
('.nff') files.
If '-g' is specified, only the '.geom' file is created, preserving the
current '.nff' file. The '-g' flag can be specified only with '-c'.
In practice it may be useful to create a low resolution approximation
of the model, change viewing/shading parameters in the '.nff' file until
a good view and/or surface quality is found and then run Irit2Nff once more
to create a high resolution approximation of the geometry using '-g'.
Here is a simple example:
@\begin{verbatim}
irit2nff -c -l -f 5 b58.dat
@\end{verbatim}
creates b58.nff and b58.geom with low resolution (FineNess of 5).
Once done with parameter setting, a fine approximation of the model can
be created with:
@\begin{verbatim}
irit2nff -c -l -g -f 25 b58.dat
@\end{verbatim}
which will only recreate b58.geom (becuase of the -g option).
Each time a data file is saved in {\em IRIT}, it can be saved with the viewing
matrix of the last INTERACT by saving the VIEW\_MAT object as well. I.e.:
@\begin{verbatim}
save( "b58", list( view_mat, b58 ) );
@\end{verbatim}
However one can overwrite the viewing matrix by appending a new matrix in the
end of the command line, created by poly3d:
@\begin{verbatim}
poly3d b58.dat
irit2nff -l -f 5 b58.dat generic0.mat
@\end{verbatim}
where generic0.mat is the viewing matrix created by poly3d.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Advanced Usage}
&Advanced Usage
One can specify surface qualities for individual surfaces of a model.
Several such attributes are supported by Irit2Nff and can be set within {\em IRIT}.
See also the ATTRIB {\em IRIT} command.
If a certain surface should be finer than the rest of the scene, one can
set a "resolution" attribute which specifies the {\em relative} FineNess resolution
of this specific surface. For example:
@\begin{verbatim}
attrib( srf1, "resolution", 2 );
@\end{verbatim}
will force srf1 to have twice the default resolution, as set via the '-f'
flag.
Almost flat patches are converted to polygons. The rectangle can be
converted into two polygons (by subdividing along one of its diagonals) or
into four by introducing a new point at the patch center. This behaviour is
controlled by the '-4' flag, but can be overwritten for individual surfaces
bu setting "twoperflat" or "fourperflat".
NFF specific properties are controlled via the following attributes:
"kd", "ks", "shine", "trans", "index". Refer to NFF manual for detail.
For example:
@\begin{verbatim}
attrib( srf1, "kd", "0.3" );
attrib( srf1, "shine", "30" );
@\end{verbatim}
Surface color is controlled in two levels. If the object has an RGB
attribute it is used. Otherwise a color as set via {\em IRIT} COLOR
command is being used if set. The later allowes you to specify only the
3 additive, 3 substractive and white and black and so is very limited for
rendering purposes. Example:
@\begin{verbatim}
attrib( tankBody, "rgb", "244,164,96" );
@\end{verbatim}
Current implementation allows white spaces in neither the attribute
name nor in the attribute value.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{Dat2Irit - Data To IRIT file filter}
!DAT2IRIT - Data To IRIT file filter
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Command Line Options}
&Command line options
@\begin{verbatim}
dat2irit [-z] DFiles
@\end{verbatim}
@\begin{itemize}
@\item
{\bf -z}: Print version number and current defaults.
@\end{itemize}
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\subsection{Usage}
&Usage
It may be sometimes desired to convert .dat data files into a form that
can be fed in back to {\em IRIT} - a '.irt' file. This filter will do exactly that.
Example:
@\begin{verbatim}
dat2irit b58.dat > b58-new.irt
@\end{verbatim}
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
@\section{Data File Format}
!DATAFILE Format
This section describes the data file format used to exchange data between
{\em IRIT} and its accompanied tools.
@\begin{verbatim}
[OBJECT {ATTRS} OBJNAME
[NUMBER n]
| [VECTOR x y z]
| [CTLPT POINT_TYPE {w} x y {z}]
| [STRING "a string"]
| [MATRIX m00 ... m03
m10 ... m13
m20 ... m23
m30 ... m33]
;A polyline should be drawn from first point to last. Nothing is drawn
;from last to first (in close polyline last pt is equal to first).
| [POLYLINE {ATTRS} #PTS ;#PTS = number of points.
[{ATTRS} x y z]
[{ATTRS} x y z]
.
.
.
[{ATTRS} x y z]
]
;Defines a closed region boundary. Last point is NOT equal to first
;and a line from last point to first should be drawn when the polygon
;boundary is drawn.
| [POLYGON {ATTRS} #PTS
[{ATTRS} x y z]
[{ATTRS} x y z]
.
.
.
[{ATTRS} x y z]
]
;Defines a cloud of points. This entry is not supported by IRIT.
| [POINTLIST {ATTRS} #PTS
[{ATTRS} x y z]
[{ATTRS} x y z]
.
.
.
[{ATTRS} x y z]
]
;Defines a bezier curve with #PTS control points. If the curve is
;rational, the rational component is introduced first.
| [CURVE BEZIER {ATTRS} #PTS POINT_TYPE
[{ATTRS} {w} x y z ...]
[{ATTRS} {w} x y z ...]
.
.
.
[{ATTRS} {w} x y z ...]
]
;Defines a bezier surface with #UPTS * #VPTS control points. If the
;surface is rational, the rational component is introduced first.
;Points are printed raw after raw (#UPTS per raw), #VPTS raws.
| [SURFACE BEZIER {ATTRS} #UPTS #VPTS POINT_TYPE
[{ATTRS} {w} x y z ...]
[{ATTRS} {w} x y z ...]
.
.
.
[{ATTRS} {w} x y z ...]
]
;Defines a BSPLINE curve of order ORDER with #PTS control points. If the
;curve is rational, the rational component is introduced first.
;Note length of knot vector is equal to #PTS + ORDER.
| [CURVE BSPLINE {ATTRS} #PTS ORDER POINT_TYPE
[KV {ATTRS} kv0 kv1 kv2 ...] ;Knot vector
[{ATTRS} {w} x y z ...]
[{ATTRS} {w} x y z ...]
.
.
.
[{ATTRS} {w} x y z ...]
]
;Defines a BSPLINE surface with #UPTS * #VPTS control points, of order
;UORDER by VORDER. If the surface is rational, the rational component
;is introduced first.
;Points are printed raw after raw (#UPTS per raw), #VPTS raws.
| [SURFACE BSPLINE {ATTRS} #UPTS #VPTS UORDER VORDER POINT_TYPE
[KV {ATTRS} kv0 kv1 kv2 ...] ;U Knot vector
[KV {ATTRS} kv0 kv1 kv2 ...] ;V Knot vector
[{ATTRS} {w} x y z ...]
[{ATTRS} {w} x y z ...]
.
.
.
[{ATTRS} {w} x y z ...]
]
POINT_TYPE -> E2 | E3 | P2 | P3
ATTRS -> [ATTRNAME ATTRVALUE]
| [ATTRNAME ATTRVALUE] ATTRS
@\end{verbatim}
Some notes:
1. This new definition for the text file is design to minimize the
reading time and space. All information can be read without backward
or forward referencing (as used to be in the old format).
2. An OBJECT can hold any number of geometry entities such as POLYGONs or
CURVEs. It is not recommended at this time to have more than one curve
or one surface in an object since this feature is not fully implemented
for free form objects.
3. An OBJECT must not hold different geometry or other entities.
I.e. CURVEs, SURFACEs, and POLYGONs must all be in different OBJECTs.
4. Attributes should be ignored if not needed. The attribute list may have
any length and is always terminated by a token that is NOT '\verb+[+'. This
simplified and disambiguous the parsing.
5. Comments may appear between '\verb+[+OBJECT ...\verb+]+' blocks, or immediatelly after
OBJECT OBJNAME, and only there.
A comment body can be anything not containing the '\verb+[+' or the '\verb+]+' tokens
(signals start/end of block). Some of the comments in the above definition
are {\em illegal} and appear there only of the sake of clarity.
6. It is prefered that geometric attributes such as NORNALs will be saved in
the geometry strurcture level (POLYGON, CURVE or vertices) while graphical
and others such as COLORs will be saved in the OBJECT level.
7. Objects may be contained in other objects to any level.
Here is an example that exercises most of the data format:
@\begin{verbatim}
This is a legal comment in a data file.
[OBJECT DEMO
[OBJECT REAL_NUM
And this is also a legal comment.
[NUMBER 4]
]
[OBJECT A_VECTOR
[VECTOR 1 2 3]
]
[OBJECT CTL_POINT
[CTLPT E3 1 2 3]
]
[OBJECT STR_OBJ
[STRING "string"]
]
[OBJECT UNIT_MAT
[MATRIX
1 0 0 0
0 1 0 0
0 0 1 0
0 0 0 1
]
]
[OBJECT [COLOR 4] POLY1OBJ
[POLYGON [PLANE 1 0 0 0.5] 4
[-0.5 0.5 0.5]
[-0.5 -0.5 0.5]
[-0.5 -0.5 -0.5]
[-0.5 0.5 -0.5]
]
[POLYGON [PLANE 0 -1 0 0.5] 4
[0.5 0.5 0.5]
[-0.5 0.5 0.5]
[-0.5 0.5 -0.5]
[0.5 0.5 -0.5]
]
]
[OBJECT [COLOR 63] ACURVE
[CURVE BSPLINE 16 4 E2
[KV 0 0 0 0 1 1 1 2 3 4 5 6 7 8 9 10 11 11 11 11]
[0.874 0]
[0.899333 0.0253333]
[0.924667 0.0506667]
[0.95 0.076]
[0.95 0.76]
[0.304 1.52]
[0.304 1.9]
[0.494 2.09]
[0.722 2.242]
[0.722 2.318]
[0.38 2.508]
[0.418 2.698]
[0.57 2.812]
[0.57 3.42]
[0.19 3.572]
[0 3.572]
]
]
[OBJECT [COLOR 2] SOMESRF
[SURFACE BEZIER 3 3 E3
[0 0 0]
[0.05 0.2 0.1]
[0.1 0.05 0.2]
[0.1 -0.2 0]
[0.15 0.05 0.1]
[0.2 -0.1 0.2]
[0.2 0 0]
[0.25 0.2 0.1]
[0.3 0.05 0.2]
]
]
@\end{verbatim}
@\section{Bugs and Limitations}
!BUGS and LIMITATIONS
Like any program of more than one line it is far from been perfect.
Some limitations as well as simplifications are layed out below.
1. No intersection of co-planar polygons is allowed. Such case results are
undefined. Most of the time, one can move one of the operands
in the Boolean operation by an EPSILON. Such EPSILON should be in the
order of 10-3 if the system uses float and and 10-6 if doubles are used.
(the UNIX and MSDOS DJGPP version uses doubles, MSDOS BC++ uses floats).
2. If the intersection curve of two objects falls exactly on polygon
boundaries, for all polygons, the system will scream that the two object
do not intersect at all. Again, try to move one by EPSILON into the other.
I probably should fix this one - that suppose to be relatively easy.
3. Avoid degeneracies - intersection that results with a point or a line will
probably cause wrong propagation of the inner and outer part of one object
relative to the other. Always extend your object beyond the other object.
4. If two objects have no intersection in their boundary, {\em IRIT} assumes they
are disjoint: a union simply combines them, and the other Boolean
operators return NULL object. One should find FAST way (3D Jordan
theorem) to find the relation between the two (A in B, B in A, A
disjoint B) and according to that make a decision.
5. Sweep of a circular curve along circular curve does {\em not} create an
exact piece of a torus. This is probably due to the fact that both curves
are rationals.
6. No degree raising for Bspline surfaces of order larger than two.
@\end{document}